DataTable part

A DataTable part consists of a collection of data in tabular form that you can make available throughout an application. Unlike other data parts, you declare each DataTable part in its own EGL source file. A DataTable is a main part, which means that you must define it in a file that has no other main parts, and it must have the same name as the file.

Include a DataTable in a use statement to make it visible to a program, library, or handler. When you use the DataTable as a message table only, you can connect the DataTable to the program through the msgTablePrefix property of the program.

The DataTable part has a required property, contents, that specifies a two-dimensional array of values for the table. See DataTable properties and the example later in this topic.

For each column of data that you specify with the contents property, you must include a variable declaration. These variable declarations are structure fields, similar to those in a structured record (see Record part). Structure fields always have a fixed length (for example, no STRING variables of undefined length are allowed). You can substructure these declarations by assigning a numeric prefix; otherwise, EGL assumes all fields are at the same level. You can specify contents only for the highest level fields (those with the lowest level number) in the structure, not for the substructure fields. For more information, see the examples later in this topic.

Syntax

DataTablePartName: The name for the data table. All programs or handlers that use the table access it by using this name. See "Compatibility" in this topic.
stereotype: The stereotype that specializes the DataTable for a specific use; see "Stereotypes." For a list of available stereotypes, see "DataTable stereotypes" in this topic. If you do not specify a stereotype here, EGL assumes the BasicTable stereotype.
columnDeclarations: A list of fixed length structure fields, each specifying a type of data for each of the columns in the table. As with any other variable declaration, each must end in a semicolon (;).
properties: A set-values block containing properties for the data table. One of these properties, contents, is required, and provides an array of literal data for the data table. For details, see DataTable properties.

DataTable stereotypes

You can specialize a DataTable part with one of the following stereotypes:

BasicTable

Contains information that is used in the program logic, such as a list of countries and related codes. This is the default stereotype.

MatchInvalidTable

Contains information in the first column that is compared to user input. The user input must differ from all provided values. This stereotype is used with UI technologies; the DataTable is typically assigned to the validatorDataTable property of a field. If the validation fails, EGL displays an error message.

MatchValidTable

Contains information in the first column that is compared to user input. The user input must match one of the provided values. This stereotype is used with UI technologies; the DataTable is typically assigned to the validatorDataTable property of a field. If the validation fails, EGL displays an error message.

MsgTable

Contains messages that a program might need to display at run time. The mechanisms for displaying runtime messages are a function of the individual UI technology. This type of DataTable has a name in the following form:

A one- to four-character prefix (such as "MT1")
A three-character national language code (see the "National language codes" appendix).

For US English, the name of the table would be "MT1ENU". You can associate a DataTable with a program if you set the msgTablePrefix program property to the prefix.

rangeChkTable

Contains information in the first and second columns that is compared to user input. The user input must match a value that is between the values in the first and second column of at least one data table row. (The range is inclusive; the user input is valid if it matches a value in the first or second column of any row.)

Using the data table

After you create the DataTable, you can write EGL code to access the information in the table. Unlike the process with many EGL parts, you do not create a variable based on the DataTable part. Instead you refer to the data table using the name that you assigned to the part. Using dot syntax, refer to a column by one of the names you assigned in the column declaration, followed by an index for the row number, as in the following example:

strTest = myDataTable.column3[4];

In this example, the STRING variable strTest contains the value from the third column, fourth row of the data table.

Examples

The following example shows a DataTable part:

DataTable myErrorMessages type MsgTable
  { shared = yes }
  msgNum INT;
  msgText char(30);

  { contents = [  
  [ 101, "File not found" ] ,
  [ 102, "Read error" ] ,  
  [ 103, "Write error" ] ]
  } 
end

You can access that table from a program by using the following code:

Function displayError(index INT in)
  strTest = 
    formatNumber(myErrorMessages.msgNum[index]) +
    "    " +
    myErrorMessages.msgText[index];
  sysLib.writeStdout(strTest);
end

With an index value of 2, the function displays the following error message:

102   Read error

You can substructure the column declarations, as in the following example:

DataTable myDataTable type basicTable 
  { shared = yes } 
    10 myColumn1 CHAR(10);
    	15 Column1A CHAR(5);
    	15 Column1B CHAR(5);
    10 myColumn2 CHAR(10); 
    10 myColumn3 CHAR(10); 
    
    { contents = [
	
	[ "ABCDEFGHIJ", "row1 col2", "row1 col3" ] , 
	[ "KLMNOPQRST", "row2 col2", "row2 col3" ] , 
	[ "1234567890", "row3 col2", "row3 col3" ] ] }
end

You can then access this data in a program that uses the table, as in the following example:

  writeStdOut(myDataTable.Column1B[1]); // displays FGHIJ

In most environments, you can modify the contents of a DataTable at runtime. Changes made at run time are visible to every program that has access to the DataTable, and the changes remain until the DataTable is unloaded. The ability to make changes and the visibility of those changes to other programs in the run unit is affected by the target system and the shared property. The unloading of the DataTable is affected by the target system and by the resident property. For more information, see DataTable properties.

You might typically modify the contents of a DataTable at run time when you have data that is relatively constant (for example, a parameter that only changes once a year), but is used in many programs. The following example shows such a DataTable:

DataTable myConstants type basicTable
  10 myConstant1 INT;
  10 myConstant2 CHAR(10);
  {contents = [ [ 0, ""]]}        //  single row with initial values
end

Then you could update the DataTable from a database or file at run time, as in the following example code:

get constantInfo;
myConstants.myconstant1[1] = constantInfo.myconstant1;
myConstants.myconstant2[1] = constantInfo.myconstant2;

The advantage of using this technique over declaring the constants in your program is that you simply need to update the database when the data changes; there is no need to change the constants in each program. Depending on the environment, this use of the DataTable might give you better performance than using a library or database. For example, in CICS®, you might define the DataTable as resident and initialize it during the startup for a CICS® region.

Compatibility

Table 1. Compatibility considerations for DataTable
Platform	Issue
COBOL generation	DataTable names have a maximum length of 7 characters
JavaScript™ generation	DataTable is not supported
JSF Handler	Inserts for messages in a msgTable type DataTable are supported; the first insert is {0}.
Text UI	Inserts for messages in a msgTable type DataTable are not supported.
Web transactions	Inserts for messages in a msgTable type DataTable are supported; the first insert is {1}.