Dictionary

A dictionary part is a part that is always available; you do not define it. A variable that is based on a dictionary part may include a set of keys and their related values, and you can add and remove key-and-value entries at run time. The entries are treated like fields in a record.

An example of a dictionary declaration is as follows:
  row Dictionary 
    {
      ID        = 5,
      lastName  = "Twain",
      firstName = "Mark",
    };

When you include entries in the declaration, each key name is an EGL identifier that must be consistent with the EGL naming conventions. When you add entries at run time, you have greater flexibility; you can specify a string literal, constant, or variable, and in this case the content can be an EGL reserved word or can include characters that would not be valid in an identifier. For details, see Bracket syntax for dynamic access.

Example assignments are as follows:
  row.age = 30;
  row["Credit"] = 700;
  row["Initial rating"] = 500
If you attempt to assign a key that already exists, you override the existing key-and-value entry. The following assignment is valid and replaces "Twain" with "Clemens":
  row.lastname = "Clemens";
Assignments also can be used for data retrieval:
  lastname String
  age, credit, firstCredit int;

  lastname = row.lastname; 
  age = row.age;
  credit = row.credit;
  credit = row["Credit"];
  firstCredit = row["Initial rating"];
The value in a key-and-value entry is of type ANY, which means that you can put different kinds of information into a single dictionary. Each value can be any of these:
Putting a variable into a dictionary assigns a copy of the variable. Consider the following record part:
  Record myRecordPart
	   x int;
	 end

The next code places a variable of type myRecordPart into the dictionary, then changes a value in the original variable:

  testValue int;

  myRecord myRecordPart;

  // sets a variable value and places
  // a copy of the variable into the dictionary.
  myRecord.x = 4; 
  row Dictionary
  {
    theRecord myRecord;
  } 
	
  // Places a new value in the original record.
  myRecord.x = 700;

  // Accesses the dictionary's copy of the record, 
  // assigning 4 to testValue.
  testValue = row.theRecord.x;
Assigning one dictionary to another replaces the target content with the source content and overrides the values of the target dictionary's properties, which are described later. The conditional statement in the following code is true, for example:
  row Dictionary { age = 30 };

  newRow Dictionary { };
  newRow = row

  // resolves to true
  if (newRow.age == 30)
    ;
  end

A set of properties in the declaration affect how the dictionary is processed. A set of dictionary-specific functions provide data and services to your code.

Dictionary properties

Each property-and-value entry is syntactically equivalent to a key-and-value entry, as shown in this example, and the entries can be in any order:
  row Dictionary 
    { 
      // properties 
      caseSensitive = no,
      ordering = none,  
     
      // fields
      ID        = 5,
      lastName  = "Twain",
      firstName = "Mark"
      age = 30;
    };
Your code can neither add nor retrieve a property or its value. In the unlikely event that you wish to use a property name as a key, use the variable name as a qualifier when you specify or refer to the key, as in this example:
  row Dictionary 
    { 
      // properties 
      caseSensitive = no,
      ordering = none,  
     
      // fields
      row.caseSensitive = "yes"
      row.ordering = 50,
      age = 30
    };
Properties are as follows:
caseSensitive
Indicates whether retrieval of a key or the related value is affected by the case of the key with which that value was stored. Options are as follows:
No (the default)
Key access is unaffected by the case of the key, and the following statements are equivalent:
  age = row.age;
  age = row.AGE;
  age = row["aGe"];
Yes
The following statements can have different results, even though EGL is primarily a case-insensitive language:
  age = row.age;
  age = row.AGE;
  age = row["aGe"];

The value of the property caseSensitive affects the behavior of several of the functions described in a later section.

ordering
Indicates how key-and-value entries are ordered for purpose of retrieval. The value of this property affects the behavior of the functions getKeys and getValues, as described in a later section.

Options are as follows:

None (the default)
Your code cannot rely on the order of key-and-value entries.

When the value of the property ordering is None, the ordering of keys (when the function getKeys is invoked) may not be the same as the ordering of values (when the function getValues is invoked).

ByInsertion
The key-and-value pairs are available in the order in which they were inserted. Any entries in the declaration are considered to be inserted first, in left-to-right order.
ByKey
The key-and-value pairs are available in key order.

Dictionary functions

To invoke any of the following functions, qualify the function name with the name of the dictionary, as in this example when the dictionary is called row:
  if (row.containsKey(age))
    ; 
  end

containsKey()

  dictionaryName.containsKey(key String in) returns (Boolean)

This function resolves to true or false, depending on whether the input string (key) is a key in the dictionary. If the dictionary property caseSensitive is set to no, case is not considered; otherwise, the function seeks an exact match, including by case.

containsKey is used only in a logical expression.

getKeys()

  dictionaryName.getKeys ( ) returns (String[ ])

This function returns an array of strings, each of which is a key in the dictionary.

If the dictionary property caseSensitive is set to no, each returned key is in lower case; otherwise, each returned key is in the case in which the key was stored.

If the dictionary property ordering is set to no, you cannot rely on the order of the returned keys; otherwise, the order is as specified in the description of that property.

getValues()

  dictionaryName.getValues ( ) returns (ANY[ ])

This function returns an array of values of any type. Each value is associated with a key in the dictionary.

insertAll()

  dictionaryName.insertAll(sourceDictionary Dictionary in)

This function acts as if a series of assignment statements copies the key-and-value entries in the source dictionary (sourceDictionary) to the target, which is the dictionary whose name qualifies the function name.

If a key is in the source and not in the target, the key-and-value entry is copied to the target. If a key is in both the source and target, the value of the source entry overrides the entry in the target. The determination of whether a key is in the target matches one in the source is affected by the value of property caseSensitive in each dictionary.

This function is different from the assignment of one dictionary to another because the function insertAll retains these entries:
  • The property-and-value entries in the target; and
  • The key-and-value entries that are in the target but not the source.

removeElement()

  dictionaryName.removeElement(key String in)

This function removes the entry whose input string (key) is a key in the dictionary. If the dictionary property caseSensitive is set to no, case is not considered; otherwise, the function seeks an exact match, including by case.

removeAll()

  dictionaryName.removeAll( )

This function removes all key-and-value entries in the dictionary, but has no effect on the dictionary's properties.

size()

  dictionaryName.size( ) returns (INT)

Returns an integer that indicates the number of key-and-value entries in the dictionary.

Related reference
Logical expressions

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.