iSeries EGL

All things EGL for the iSeries / i5 / Power System

Archive for February 2013

Performing Lookups Using Dictionaries

leave a comment »

Using Dictionary Records to Support Lookup Operations

This post shows how to use EGL’s Dictionary Record construct to facilitate lookup operations similar to the manner seen using Java’s ArrayList.


The Lookup Problem

In application development, it is common to have the user select an item from a list. The item is often a description of an inventory item or may be a status of an invoice.

What follows is a description of what happens when a user selects a status description from a list that must be translated into a two-byte code prior to storing that code in a record field. Likewise, when the record is read, the two-byte code must be translated into its long description equivalent prior to displaying it to the user.

The list below shows the values stored on disk on the left with the corresponding long description which are always presented to the user, on the right.

  • OP – Open
  • AC – Active
  • CL – Closed
  • ST – Started
  • CN – Canceled
  • PR – Processed

These are often called name/value pairs and they can be loaded into an EGL Dictionary Record in a manner that allows lookups to be performed by using the key-value on the left side. Depending upon the manner in which they are initially loaded during the application’s start-phase, lookups can be performed using the short, two-byte code which returns the longer description, or by using the description which returns the shorter code.

The list above describes one ordering that is needed to lookup by the code. The list below shows the ordering needed to lookup by description. In either case, the key-value is on the left side.

  • Open – OP
  • Active – AC
  • Closed – CL
  • Started – ST
  • Canceled – CN
  • Processed – PR

Shown below is the EGL Record that is used to define the dictionary for the status code dictionary (requestStatusCodeDictionary) and its corresponding status description dictionary (requestStatusDescriptionDictionary).

record RequestStatusDictionaryRecord type BasicRecord
	//requestStatusCodeDictionary contains keys representing the short code so that the long
	//description can be obtained.  Used for converting the short code read from disk to the
	//long description. This is important so that the combobox can show the record's current
	//selection as it has been persisted to disk.
	requestStatusCodeDictionary Dictionary   {
        caseSensitive = yes,
        ordering = OrderingKind.byKey  

	//requestStatusDescriptionDictionary contains keys representing the long description so 
        //that the short code can be obtained.  Used for converting the combobox selection to the 
	//short code which is to be written to disk.
	requestStatusDescriptionDictionary Dictionary   {
        caseSensitive = no,
        ordering = OrderingKind.byKey  


Fig.1 – The EGL Record used to define the Dictionaries


Loading the Dictionaries

The EGL function shown below is placed into a Library type. The function is called early in the application’s RichUI start() function so that the name/value pairs for each are loaded accordingly.

//* This function loads the RequestStatusDictionaryRecord's requestStatusCodeDictionary 
//* with the name/value pairs representing the long description and the short code.
//* It also loads the requestStatusDescriptionDictionary with the short codes and 
//* the long description.
function loadRequestStatusCodesAndDescriptions()
	//Populate the Codes dictionary
	requestStatusDictionaryRecord.requestStatusCodeDictionary["Open" as string] = "OP";
	requestStatusDictionaryRecord.requestStatusCodeDictionary["Active" as string] = "AC";
	requestStatusDictionaryRecord.requestStatusCodeDictionary["Closed" as string] = "CL";
	requestStatusDictionaryRecord.requestStatusCodeDictionary["Started" as string] = "ST";
	requestStatusDictionaryRecord.requestStatusCodeDictionary["Imaging" as string] = "IM";
	requestStatusDictionaryRecord.requestStatusCodeDictionary["Delivered" as string] = "DL";
	requestStatusDictionaryRecord.requestStatusCodeDictionary["Cancelled" as string] = "CN";
	requestStatusDictionaryRecord.requestStatusCodeDictionary["Returned" as string] = "RT";
	requestStatusDictionaryRecord.requestStatusCodeDictionary["Processed" as string] = "PR";
	//Populate the Descriptions dictionary
	requestStatusDictionaryRecord.requestStatusDescriptionDictionary["OP" as string] = "Open";
	requestStatusDictionaryRecord.requestStatusDescriptionDictionary["AC" as string] = "Active";
	requestStatusDictionaryRecord.requestStatusDescriptionDictionary["CL" as string] = "Closed";
	requestStatusDictionaryRecord.requestStatusDescriptionDictionary["ST" as string] = "Started";
	requestStatusDictionaryRecord.requestStatusDescriptionDictionary["IM" as string] = "Imaging";
	requestStatusDictionaryRecord.requestStatusDescriptionDictionary["DL" as string] = "Delivered";
	requestStatusDictionaryRecord.requestStatusDescriptionDictionary["CN" as string] = "Cancelled";
	requestStatusDictionaryRecord.requestStatusDescriptionDictionary["RT" as string] = "Returned";
	requestStatusDictionaryRecord.requestStatusDescriptionDictionary["PR" as string] = "Processed";	
	SysLib.writeStderr("SessionLibrary.loadRequestStatusCodesAndDescriptions : Dumping contents of requestStatusCodeDictionary");
	keys string[] = requestStatusDictionaryRecord.requestStatusDescriptionDictionary.getKeys();
	values  any[] = requestStatusDictionaryRecord.requestStatusDescriptionDictionary.getValues();
	SysLib.writeStderr("SessionLibrary.loadRequestStatusCodesAndDescriptions : Codes - Description");
	for(i int from 1 to keys.getSize())
		SysLib.writeStderr("SessionLibrary.loadRequestStatusCodesAndDescriptions : key=" + StrLib.upperCase(keys[i]) + "            value="+values[i] );	 
        //List the values of each to the console
	keys  = requestStatusDictionaryRecord.requestStatusCodeDictionary.getKeys();
	values   = requestStatusDictionaryRecord.requestStatusCodeDictionary.getValues();
	SysLib.writeStderr("SessionLibrary.loadRequestStatusCodesAndDescriptions : Description - Codes");
	for(i int from 1 to keys.getSize())
		SysLib.writeStderr("SessionLibrary.loadRequestStatusCodesAndDescriptions : key=" + keys[i] + "            value="+values[i] );	 

Fig.2 – Loading the name/value pairs into each dictionary

The code segment at the end is not required. It is presented only to show the results of the loading process by listing the contents of each dictionary to the console. The list is presented below.

SessionLibrary.loadRequestStatusCodesAndDescriptions : Dumping contents of requestStatusCodeDictionary 
SessionLibrary.loadRequestStatusCodesAndDescriptions : Codes - Description 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=AC value=Active 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=CL value=Closed 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=CN value=Cancelled 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=DL value=Delivered 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=IM value=Imaging 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=OP value=Open 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=PR value=Processed 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=RT value=Returned 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=ST value=Started 

SessionLibrary.loadRequestStatusCodesAndDescriptions : Description - Codes 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=Active value=AC 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=Cancelled value=CN 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=Closed value=CL 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=Delivered value=DL 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=Imaging value=IM 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=Open value=OP 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=Processed value=PR 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=Returned value=RT 
SessionLibrary.loadRequestStatusCodesAndDescriptions : key=Started value=ST 

Fig.3 – The name/value pairs of each dictionary as listed in the console.


Looking up by Description

The code shown below shows how to perform a lookup operation using the long description, for example, “Closed” which was selected from the ComboBox. The result of the operation i.e. “CL” will be placed into the field named requestStatusCode.

	//The record status code is obtained by using the recordStatusComboBox.value as the lookup
	//key into the requestStatusDictionaryRecord which was created during the start() of Page01.
	requestStatusDictionaryRecord RequestStatusDictionaryRecord = SessionLibrary.getRequestStatusDictionaryRecord();
	requestStatusCode string = requestStatusDictionaryRecord.requestStatusCodeDictionary[selectedRecordStatus]; 

Fig.4 – Performing a lookup using the status description to return its code.


Looking up by Code

To get the longer description of the status code, the code listed below is used.

	requestStatusDictionaryRecord RequestStatusDictionaryRecord = SessionLibrary.getRequestStatusDictionaryRecord();
	requestStatusDescription string = requestStatusDictionaryRecord.requestStatusDescriptionDictionary[statusCode];

Fig.5 – Performing a lookup using the status code to return its description.



Now, keep looking up.

Written by iseriesadmin

February 6, 2013 at 12:27 pm