Beginning with SAS 9, the hash object is available for use in a DATA step. The hash object provides an efficient, convenient mechanism for quick data storage and retrieval.

Unlike an array, which uses a series of consecutive integers to address array elements, a hash object can use any combination of numeric and character values as addresses. Also unlike arrays, which return only a single value, hash objects can return multiple values from a given lookup. A hash object can be loaded from hardcoded values or a SAS data set, is sized dynamically, and exists for the duration of the DATA step.

The hash object is a good choice for lookups that use unordered data that can fit into memory because it provides in-memory storage and retrieval and does not require the data to be sorted or indexed.

When a lookup depends on character key values, you can use the hash object. A hash object resembles a table with rows and columns and contains a key component and a data component.

The key component has these characteristics:

The data component has these characteristics:

Suppose you have a data set named Sasuser.Contrib that lists the quarterly contributions to a retirement fund. You can use the hash object to calculate the difference between the actual contribution and the goal amount for each quarter.

The following program creates a hash object that stores the quarterly goal for employee contributions to the retirement fund. To calculate the difference between actual contribution and the goal amount, the program retrieves the goal amount from the hash object based on the key values.

data work.difference (drop= goalamount);
   if _N_ = 1 then do;
      declare hash goal( );
      goal.definekey("QtrNum");
      goal.definedata("GoalAmount");
      goal.definedone( ); 
      call missing(goalamount);
      goal.add(key:'qtr1', data:10 );
      goal.add(key:'qtr2', data:15 );
      goal.add(key:'qtr3', data: 5 );
      goal.add(key:'qtr4', data:15 );
  end;
  set sasuser.contrib;
  goal.find();
  Diff = amount - goalamount;
run;

We will see how the hash object is set up.

The hash object is a DATA step component object. Component objects are data elements that consist of attributes and methods. Attributes are the properties that specify the information that is associated with an object. Methods define the operations that an object can perform.

To use a DATA step component object in your SAS program, you must first declare and create (instantiate) the object.

You declare a hash object using the DECLARE statement.

The following DECLARE statement creates a hash object named Goal.

data work.difference (drop= goalamount);
   if _N_ = 1 then do;
      declare hash goal();

At this point, you have declared a hash object named Goal.

Remember that the hash object uses lookup keys to store and retrieve data. The keys and the data are DATA step variables that you use to initialize the hash object by using object dot notation method calls.

A key component is defined by passing the key variable name to the DEFINEKEY method. A data component is defined by passing the data variable name to the DEFINEDATA method. When all key and data components are defined, the DEFINEDONE method is called. Keys and data can consist of any number of character or numeric DATA step variables.

The following code initializes the key variable QtrNum and the data variable GoalAmount.

data work.difference (drop= goalamount);
   length goalamount 8;
   if _N_ = 1 then do;
      declare hash goal();
      goal.definekey ("QtrNum");
      goal.definedata ("GoalAmount");
      goal.definedone();

Since the variable GOALAMOUNT is not in an input data set and does not appear on the left side of an equal sign in an assignment statement, SAS issues a note stating that this variable is not initialized.

To avoid receiving these notes, use the CALL MISSING routine with the key and data variables as parameters. The CALL MISSING routine assigns a missing value to the specified character or numeric variables.

data Work.Difference (drop= goalamount);
if _N_ = 1 then do; declare hash goal();
   goal.definekey("QtrNum");
   goal.definedata("GoalAmount");
   goal.definedone();
   call missing(goalamount);

So far, you have declared and instantiated the hash object, and initialized the hash object's key and data variables. You are now ready to populate the hash object using the ADD method. The following code uses the ADD method to load the key values qtr1, qtr2, qtr3, and qtr4 and the corresponding data values 10, 15, 5, and 15 into the hash object.

data work.difference (drop= goalamount);
if _N_ = 1 then do;
   declare hash goal( );
   goal.definekey("QtrNum");
   goal.definedata("GoalAmount");
   goal.definedone( ); 
   call missing(goalamount);
   goal.add(key:'qtr1', data:10 );
   goal.add(key:'qtr2', data:15 );
   goal.add(key:'qtr3', data: 5 );
   goal.add(key:'qtr4', data:15 );
end;

Use the FIND method to retrieve matching data from the hash object. The FIND method generates a numeric return code that indicates whether the key is found in the hash object. A return code of zero indicates a successful find. A nonzero value indicates a find failure. If the key is in the hash object, then the FIND method also sets the data variable to the value of the data item so that it is available for use after the method call.

data work.difference (drop= goalamount);
   if _N_ = 1 then do;
      declare hash goal( );
      goal.definekey("QtrNum");
      goal.definedata("GoalAmount");
      goal.definedone( ); 
      call missing(goalamount);
      goal.add(key:'qtr1', data:10 );
      goal.add(key:'qtr2', data:15 );
      goal.add(key:'qtr3', data: 5 );
      goal.add(key:'qtr4', data:15 );
   end;
   set sasuser.contrib;
   rc=goal.find();
   Diff = amount - goalamount;
run;

We will consider what happens when the program is submitted for execution.

data Work.Difference (drop= goalamount);
   if _N_ = 1 then do;
      declare hash goal( );
      goal.definekey("QtrNum");
      goal.definedata("GoalAmount");
      goal.definedone( ); 
      call missing(goalamount);
      goal.add(key:'qtr1', data:10 );
      goal.add(key:'qtr2', data:15 );
      goal.add(key:'qtr3', data: 5 );
      goal.add(key:'qtr4', data:15 );
   end;
   set sasuser.contrib;
   rc=goal.find();
   Diff = amount - goalamount;
run;

The program executes until the SET statement encounters end of file on sasuser.contrib. PROC PRINT output shows the completed data set.

proc print data=work.difference;
run;

Suppose you need to create a report that shows revenue, expenses, profits, and airport information. You have two data sets that contain portions of the required data. The SAS data set Sasuser.Revenue contains flight revenue data. The SAS data set Sasuser.Acities contains airport data, including the airport code, location, and name.

To create the report, you can use a hash object to retrieve matching airport data from Sasuser.Acities.

In the following code, the DECLARE statement creates the Airports hash object and loads it from Sasuser.Acities.

data work.report;
   if _N_=1 then do;
      declare hash airports (dataset: "sasuser.acities");

To initialize the attributes of hash variables that originate from an existing SAS data set, you can use a non-executing SET statement.

Because the IF condition is false during execution, the SET statement is compiled but not executed. The PDV is created with the variables Code, City, and Name from Sasuser.Acities.

data work.report;
   if _N_=1 then do;
      if 0 then
         set sasuser.acities (keep=Code City Name);

When you use this technique, CALL MISSING is not required.

The hash object that you worked with earlier in this chapter contains one key variable and one data variable. In this example, you need to associate more than one data value with each key.

In the following code, the DECLARE statement creates the Airports hash object and loads it from Sasuser.Acities. The DEFINEKEY method call defines the key to be the value of the variable Code. The DEFINEDATA method call defines the data to be the values of the variables City and Name.

data work.report;
      if 0 then
         set sasuser.acities (keep=Code City Name);
   if _N_=1 then do;
   declare hash airports (dataset: "sasuser.acities")
   airports.definekey ("Code");
   airports.definedata ("City", "Name");
   airports.definedone();
end;

hashobject.DEFINEDATA (ALL:“YES”);

You can use the FIND method multiple times in order to retrieve multiple data values. In the following program, the FIND method retrieves the values of City and Name from the Airports hash object based on the value of Origin.

data work.report;
   if _N_=1 then do;
        if 0 then set sasuser.acities (keep=Code City Name);
      declare hash airports (dataset: "sasuser.acities");
      airports.definekey ("Code");
      airports.definedata ("City", "Name");
      airports.definedone();
   end;
 set sasuser.revenue;
 rc=airports.find(key:origin);
 OriginCity=city;
 OriginAirport=name;
 rc=airports.find(key:dest);
DestCity=city;
DestAirport=name;
run;

PROC PRINT output shows the completed data set.

proc print data=work.report;
   var origin dest flightid date origincity originairport
      destcity destairport;
run;

Remember that method calls generate a numeric return code that indicates whether the method succeeded or failed. A value of 0 indicates that the method succeeded. A nonzero value indicates that the method failed.

To store the value of the return code in a variable, specify the variable name RC at the beginning of the method call. Here is an example:

     rc=hashobject.find (key:keyvalue);

The return code variable can be used in conditional logic to ensure that the FIND method found a KEY value in the hash object that matches the KEY value from the PDV.

Error messages are written to the log when the following program is submitted.

data work.report;
   if _N_=1 then do;
  	     if 0 then set sasuser.acities (keep=Code City Name);
      declare hash airports (dataset: "sasuser.acities");
      airports.definekey ("Code");
      airports.definedata ("City", "Name");
      airports.definedone();
   end;
set sasuser.revenue;
airports.find(key:origin);
OriginCity=city;
OriginAirport=name;
airports.find(key:dest);
DestCity=city;
DestAirport=name;
run;

NOTE: There were 50 observations read from the data set SASUSER.ACITIES.
ERROR: Key not found.
ERROR: Key not found.
ERROR: Key not found.
ERROR: Key not found.
ERROR: Key not found.
ERROR: Key not found.
NOTE: The SAS System stopped processing this step because of errors.
NOTE: There were 142 observations read from the data set SASUSER.REVENUE.
WARNING: The data set WORK.REPORT1 may be incomplete. When this step was 
         stopped there were 142 observations and 14 variables.

A closer examination of the output shows that the data set Work.Report contains errors. For example, notice that in observations 6 through 8 the value of both OriginCity and DestCity is Canberra, Australian C and the values of OriginAirport and DestAirport are missing.

The errors occur because the Airports hash object does not include the key value WLG or a corresponding Name value for the key value CBR.

Conditional logic can be added to the program to create blank values if the values loaded from the input data set, Sasuser.Revenue, cannot be found in the Airports hash object:

data work.report;
   if _N_=1 then do;
  	     if 0 then set sasuser.acities(keep=Code City Name);
      declare hash airports (dataset: "sasuser.acities");
      airports.definekey ("Code");
      airports.definedata ("City", "Name");
      airports.definedone();
end;
set sasuser.revenue;
rc=airports.find(key:origin);
if rc=0 then do;
    OriginCity=city;
    OriginAirport=name;
end;
else do;
   OriginCity='';
   OriginAirport='';
end;
rc=airports.find(key:dest);
if rc=0 then do;
   DestCity=city;
   DestAirport=name;
end;
else do;
   DestCity='';
   DestAirport='';
end;
run;

PROC PRINT output shows the completed data set. Notice that in observations 6 through 8, the value of DestCity is now blank and no error messages appear in the log.

proc print data=work.report;
   var origin dest flightid date origincity originairport
      destcity destairport;
run;

NOTE: There were 50 observations read from the data set SASUSER.ACITIES.
NOTE: There were 142 observations read from the data set SASUSER.REVENUE.
NOTE: The data set WORK.REPORT2 has 142 observations and 15 variables.