Using the Data Dictionary

Overview

To use the data dictionary in PRO/5 programs, make calls to the EUS Toolkit utilities that query the definitions stored in the data dictionary. These utilities return string templates containing the values that define the format of the application's data files. The values returned are then assigned to variables used to control access to the data files.

This section demonstrates the use of the data dictionary based on a fragment of code. Each line of code is described in sufficient detail to use the information in your own PRO/5 programs.

Querying the Dictionary

The data dictionary is used by putting calls to data dictionary utilities in places where IOLISTs would normally be coded IOLISTs. For existing PRO/5 programs, remove the IOLISTs and replace them with data dictionary utility calls.

These calls determine the format of the application data files from the data dictionary definitions and return a string template that can then be used to read and write records. These utilities also provide information about the physical location of data files, based on the current configuration.

The code fragment below illustrates calling data dictionary utilities.

0110 LET BBEXT$=STBL("BBEXT")
0120 CALL BBEXT$+"_ddopen.utl"
0130 LET ALIAS$="CUSTOMER"
0140 CALL BBEXT$+"_ddfld.utl",
0140:ALIAS$,4,TEMPLATE$,"E"
0150 DIM CUSTOMER$:TEMPLATE$
0160 DIM ALIAS$(0)
0170 LET ALIAS$="CUSTOMER"
0180 CALL BBEXT$+"_ddfil.utl",ALIAS$,0
0190 CALL BBEXT$+"_ddclose.utl"

Lines 120 through 140 illustrate how to interactively query the data dictionary to determine the physical layout of data in this file.

Opening the Data Dictionary

Line 120 calls the _ddopen.utl routine to open the data dictionary definition files. This must be done before calling any of the other data dictionary modules.

Querying Record Format

The CUSTOMER file alias is used in the example. Line 130 assigns the file alias, "CUSTOMER", to the variable ALIAS$. The call to _ddfld.utl at line 140 is used here to get a data dictionary record definition. The value "4" in the call list is an action type indicating that _ddfld.utl should build a string template based on record layout information in the data dictionary. The template will be returned in the variable TEMPLATE$. The "E" in the call list indicates a brief template, without field attributes.

Next, dimension a string variable called CUSTOMER$ with the template that contains the current data dictionary definition with the following line:

0150 DIM CUSTOMER$:TEMPLATE$

The template was created by line 0140 above. The string template contains a list of the field names in the record with the data type and length of each field. Field definitions are separated by commas. For additional information on string templates, see String Templates in the User's Reference Guide.

Locating Data Files

The next call is to _ddfil.utl in line 0180.

0180 CALL BBEXT$+"_ddfil.utl",ALIAS$,0

This is another data dictionary utility that returns information about the file. After the call, ALIAS$ is loaded with a string template containing information about the file definition. For example, ALIAS.PATH$ contains the name of the physical file.

Normally, ALIAS.PATH$ contains at least one global value that should be resolved before attempting to open the data file. Assume ALIAS.PATH$ is loaded with the value (DATA)cust.dat, and in the configuration file, the (DATA) global has been set to (PROJECT)data/. Because PROJECT=/basis/applet_name/, the physical location of the data file is /basis/applet_name/data/cust.dat.

Before opening the data file, call another EUS module to resolve the (DATA) global string and provide an actual path name and file name with the following:

0200 LET PATHNAME$=ALIAS.PATH$
0210 CALL BBEXT$+"_setpath.utl",PATHNAME$
0220 OPEN (1) PATHNAME$

The PATHNAME$ variable is set to the value of ALIAS.PATH$ that was returned from the earlier call to _ddfil.utl. The _setpath.utl utility program resolves the global references included in the PATHNAME$ variable and returns a path and file name. These values are then used on line 220 to open the data file.

Because of the scope of the configuration file, the appropriate file name will always be opened because the program is generic in nature, and PATHNAME$ is constructed based on the current values in the configuration file.

After querying the data dictionary, call the _ddclose.utl utility to close the associated files, as shown below:

0190 CALL BBEXT$+"_ddclose.utl"

Remote Access

If an installation accesses data on a remote machine through the PRO/5 Data Server, edit the (DATA) global in the configuration file to reflect the location of the data. For example:

DATA=/<server1>/basis/data

Reading and Writing

When using the data dictionary, file I/O operations are accomplished using READ RECORD and WRITE RECORD verbs. In existing PRO/5 programs, these statements replace the I/O lists previously used. Sample lines related to the previous example are:

0300 LET CUSTOMER.CUST_NUM=10
0310 READ RECORD (1,KEY=CUSTOMER.CUST_NUM$)CUSTOMER$
0320 LET CUSTOMER$=FIELD(CUSTOMER$)
0330 LET CUSTOMER.LAST_NAME$="JONES"
0340 WRITE RECORD (1)CUSTOMER$

Remember, the CUSTOMER$ variable contains a string that is dimensioned using the template named TEMPLATE$, which was obtained from the data dictionary in line 150, above.

Using Globals to Optimize

If an application has a significant number of programs that access the data files, integrate the data dictionary during initialization and load the dictionary information into global strings. For example, the program lines shown below can be placed before the example code fragment to initialize the data dictionary definitions:

0010 CALL "_acu.utl"
0020 LET BBEXT$=STBL("BBEXT")
0030 CALL BBEXT$+"_ddopen.utl"
0040 LET ALIAS$="CUSTOMER"
0050 CALL BBEXT$+"_ddfil.utl",ALIAS$,0
0060 LET PATHNAME$=ALIAS.PATH$
0070 CALL BBEXT$+"_setpath.utl",PATHNAME$
0080 LET TRASH$=STBL("CUSTOMER_PATH",PATHNAME$)
0090 DIM ALIAS$(0)
0100 LET ALIAS$="CUSTOMER"
0110 CALL BBEXT$+"_ddfld.utl",ALIAS$,4,TEMPLATE$,"E"
0120 LET TRASH$=STBL("CUST_TEMPLATE",TEMPLATE$)
0130 CALL BBEXT$+"_ddclose.utl"

Then, remove lines 0110 through 0190 of the original example and insert the following line:

0100 DIM CUSTOMER$:STBL("CUST_TEMPLATE")

Finally, replace lines 0200 through 0220 with the following line:

0200 OPEN (1) STBL("CUSTOMER_PATH")

Because of memory constraints, this may not work in an MS-DOS environment.

The complete revised code fragment will appear as follows:

0010 CALL "_acu.utl"
0020 CALL BBEXT$+"_ddopen.utl"
0030 LET ALIAS$="CUSTOMER"
0040 CALL BBEXT$+"_ddfil.utl",ALIAS$,0
0050 LET PATHNAME$=ALIAS.PATH$
0060 CALL BBEXT$+"_setpath.utl",PATHNAME$
0070 LET TRASH$=STBL("CUSTOMER_PATH",PATHNAME$)
0080 DIM ALIAS$(0); LET ALIAS$="CUSTOMER"
0090 CALL BBEXT$+"_ddfld.utl",ALIAS$,4,TEMPLATE$,"E"
0100 LET TRASH$=STBL("CUST_TEMPLATE",TEMPLATE$)
0110 CALL BBEXT$+"_ddclose.utl"
0120 DIM CUSTOMER$:STBL("CUST_TEMPLATE")
0200 OPEN (1) STBL("CUSTOMER_PATH")
0300 LET CUSTOMER.CUST_NUM=10
0310 READ RECORD (1,KEY=CUSTOMER.CUST_NUM$)CUSTOMER$
0320 LET CUSTOMER$=FIELD(CUSTOMER$)
0330 LET CUSTOMER.LAST_NAME$="JONES"
0340 WRITE RECORD (1)CUSTOMER$