DECLARE Statement

Declares a DATA step component object; creates an instance of and initializes data for a DATA step component object

Valid: in a DATA step

Category: Action

Type: Executable

Alias: DCL

Syntax

DECLARE object variable <(< argument_tag-1 : value-1 <, ... argument_tag-n : value-n >>)>;

Arguments

object

specifies the component object. It can be one of the following:
- hash
  - indicates a hash object. The hash object provides a mechanism for quick data storage and retrieval. The hash object stores and retrieves data based on look-up keys.
  - See Also: 'Using the Hash Object' in SAS Language Reference: Concepts
- hiter
  - indicates a hash iterator object. The hash iterator object enables you to retrieve the hash object's data in forward or reverse key order.
  - See Also: 'Using the Hash Iterator Object' in SAS Language Reference: Concepts

variable

specifies the variable name for the component object.

argument_tag

specifies the information that is used to create an instance of the component object. Valid values for the argument_tag depend on the component object.

Valid hash object argument tags are
hashexp: n
- The hash object's internal table size, where the size of the hash table is 2 ⁿ .
  
  The value of hashexp is used as a power-of-two exponent to create the hash table size. For example, a value of 4 for hashexp equates to a hash table size of 2 ⁴ , or 16. The maximum value for hashexp is 16, which equates to a hash table size of 2 ¹⁶ or 65536.
  
  The hash table size is not equal to the number of items that can be stored. Imagine the hash table as an array of 'buckets.' A hash table size of 16 would have 16 'buckets.' Each bucket can hold an infinite number of items. The efficiency of the hash table lies in the ability of the hashing function to map items to and retrieve items from the buckets.
  
  You should specify the hash table size relative to the amount of data in the hash object in order to maximize the efficiency of the hash object lookup routines. Try different hashexp values until you get the best result. For example, if the hash object contains one million items, a hash table size of 16 (hashexp = 4) would work, but not very efficiently . A hash table size of 512 or 1024 (hashexp = 9 or 10) would result in the best performance.
- Default: 8, which equates to a hash table size of 2 ⁸ or 256

dataset: ' dataset_name '
- Names a SAS data set to load into the hash object.
  
  The name of the SAS data set can be a literal or character variable. The data set name must be enclosed in single or double quotation marks. Macro variables must be enclosed in double quotation marks.
  
  Note: If the data set contains duplicate keys, then the first instance will be in the hash object, and following instances will be ignored.

ordered: ' option '

Specifies whether or how the data is returned in key-value order if you use the hash object with a hash iterator object or if you use the hash object OUTPUT method.

option can be one of the following values:

' ascending ' 'a'	Data is returned in ascending key-value order. Specifying ' ascending ' is the same as specifying ' yes '.
'descending' 'd'	Data is returned in descending key-value order.
'YES' 'Y'	Data is returned in ascending key-value order. Specifying ' yes ' is the same as specifying ' ascending '.
'NO' 'N'	Data is returned in some undefined order.

Default: NO

The argument can also be enclosed in double quotation marks. The valid hash iterator object constructor is the hash object name.

See Also: 'Initializing Hash Object Data Using a Constructor' and 'Declaring and Instantiating a Hash Iterator Object' in SAS Language Reference: Concepts .

Details

The Basics

To use a DATA step component object in your SAS program, you must declare and create (instantiate) the object. The DATA step component interface provides a mechanism for accessing predefined component objects from within the DATA step.

For more information about the predefined DATA step component objects, see 'Using DATA Step Component Objects' in SAS Language Reference: Concepts .

Declaring a DATA Step Component Object You use the DECLARE statement to declare the DATA step component object.

 declare hash h;

The DECLARE statement tells SAS that the variable H is a hash object.

After you declare the new component object, use the _NEW_ statement to instantiate the object. For example, in the following line of code, _NEW_ statement creates the hash object and assigns it to the variable H:

 h = _new_ hash( );

Using the DECLARE Statement to Instantiate a DATA Step Component Object As an alternative to the two-step process of using the DECLARE and the _NEW_ statements to declare and instantiate a component object, you can use the DECLARE statement to declare and instantiate the component object in one step. For example, in the following line of code, the DECLARE statement declares and instantiates a hash object and assigns it to the variable H:

 declare hash h( );

This is equivalent to using the following code:

 declare hash h;  h = _new_ hash( );

A constructor is a method that you can use to instantiate a component object and initialize the component object data. For example, in the following line of code, the DECLARE statement declares and instantiates a hash object and assigns it to the variable H. In addition, the hash table size is initialized to a value of 16 (2 ⁴ ) using the argument tag, hashexp.

 declare hash h(hashexp: 4);

Comparisons

You can use the DECLARE statement and the _NEW_ statement, or the DECLARE statement alone to declare and instantiate an instance of a DATA step component object.

Examples

Example 1: Declaring and Instantiating a Hash Object by Using the DECLARE and _NEW_ Statements

This example uses the DECLARE statement to declare a hash object. The _NEW_ statement is used to instantiate the hash object.

 data _null_;     length k ;     length d ;     if _N_ = 1 then do;        /* Declare and instantiate hash object "myhash" */   declare hash myhash;     myhash = _new_ hash( );   /* Define key and data variables */        rc = myhash.defineKey('k');        rc = myhash.defineData('d');        rc = myhash.defineDone( );        /* avoid uninitialized variable notes */        call missing(k, d);     end;     /* Create constant key and data values */     rc = myhash.add(key: 'Labrador', data: 'Retriever');     rc = myhash.add(key: 'Airedale', data: 'Terrier');     rc = myhash.add(key: 'Standard', data: 'Poodle');     /* Find data associated with key and write data to log*/     rc = myhash.find(key: 'Airedale');     if (rc = 0) then        put d=;     else        put 'Key Airedale not found';  run;

Example 2: Declaring and Instantiating a Hash Object by Using the DECLARE Statement

This example uses the DECLARE statement to declare and instantiate a hash object in one step.

 data _null_;     length k ;     length d ;     if _N_ = 1 then do;        /* Declare and instantiate hash object "myhash" */   declare hash myhash( );   rc = myhash.defineKey('k');        rc = myhash.defineData('d');        rc = myhash.defineDone( );        /* avoid uninitialized variable notes */        call missing(k, d);     end;     /* Create constant key and data values */     rc = myhash.add(key: 'Labrador', data: 'Retriever');     rc = myhash.add(key: 'Airedale', data: 'Terrier');     rc = myhash.add(key: 'Standard', data: 'Poodle');     /* Find data associated with key and write data to log*/     rc = myhash.find(key: 'Airedale');     if (rc = 0) then        put d=;     else        put 'Key Airedale not found';  run;

Example 3: Instantiating and Initializing Data Values for a Hash Object

This example uses the DECLARE statement to declare and instantiate a hash object. The hash table size is set to 16 (2 ⁴ ).

 data _null_;     length k ;     length d ;     if _N_ = 1 then do;        /* Declare and instantiate hash object "myhash". Set hash table size to 16.*/   declare hash myhash(hashexp: 4);   rc = myhash.defineKey('k');        rc = myhash.defineData('d');        rc = myhash.defineDone( );        /* avoid uninitialized variable notes */        call missing(k, d);     end;     /* Create constant key and data values */     rc = myhash.add(key: 'Labrador', data: 'Retriever');     rc = myhash.add(key: 'Airedale', data: 'Terrier');     rc = myhash.add(key: 'Standard', data: 'Poodle');     rc = myhash.find(key: 'Airedale');     /* Find data associated with key and write data to log*/     if (rc = 0) then        put d=;     else        put 'Key Airedale not found';  run;