NAME Directive

The NAME directive assigns a field name to the field defined on the next line.

Syntax

$XFD NAME=fieldname

or

*(( XFD NAME=fieldname ))

This directive has several uses, as shown in the following examples.

Example 1

Within a database file, all field names must be unique. (Multiple database tables may include the same field name, but duplicates may not exist within a single table.) Unique field names are not required in COBOL, because names can be qualified by group items. For example, in COBOL this is done:

01  employee-record.
  03  date-hired.
    05  yy   pic 99.
    05  mm   pic 99.
    05  dd   pic 99.
  03  date-last-paid.
    05  yy   pic 99.
    05  mm   pic 99.
    05  dd   pic 99.

You need not change the field names in your COBOL program to access a database. Instead, you use the NAME directive to provide unique database names for the fields. For example:

 01  employee-record.
   03  date-hired.
     05  yy   pic 99.
     05  mm   pic 99.
     05  dd   pic 99.
   03  date-last-paid.
*(( xfd  name=year-paid ))
     05  yy   pic 99.
$xfd  name=month-paid
     05  mm   pic 99.
$xfd  name=day-paid
     05  dd   pic 99.

The dates portion of the resulting database table will look like:

yy    mm    dd    year_paid    month_paid    day_paid
88 02 15 94    04    30

Example 2

Some SQL-based databases require that names be no more than 18 characters long. For those systems, the Acu4GL run-time will automatically truncate longer COBOL names after the eighteenth character.

If you have names that are identical within the first 18 characters, or that would not be meaningful to you if shortened to the first 18 characters, you can use the NAME directive to assign them different database field names.

For example, a portion of your database might contain:

01  acme-employee-record.
  03  acme-employee-record-date-hired
      pic x(6).
  03  acme-employee-record-date-last-paid
      pic x(6).

You could add two NAME directives to differentiate the two item names by making them meaningful within 18 characters:

 01  acme-employee-record.
$xfd  name=date-hired
   03  acme-employee-record-date-hired
       pic x(6).
$xfd  name=date-last-paid
   03  acme-employee-record-date-last-paid
       pic x(6).
Note:

Your COBOL names have not changed. The new names are used only for the XFD fields.

Each time you compile your program and specify the CREATEXFD configuration variable to create XFDs, any field names longer than 18 characters will be checked for uniqueness within the first 18. If any field names are identical for the first 18 characters, a compiler warning message will be issued. A warning of this type does not prevent the program from compiling and does not prevent the XFD from being generated.

Example 3

You may want to use the NAME directive to assign shorter names than those used in your COBOL programs. This makes the formation of interactive SQL queries easier and quicker. For example:

*(( XFD  NAME=EMPNO ))
  03  employee-number  pic x(8).

This directive causes the XFD to map EMPLOYEE-NUMBER to EMPNO in the database.

Example 4

If your database already exists, and a field name in the database does not match the name used in your COBOL FD, you can use a NAME directive to associate the two names. For example:

$xfd  name=employee-no
  03  employee-number  pic x(8).

This directive causes the XFD to map EMPLOYEE-NUMBER in the COBOL program to EMPLOYEE-NO in the database.

Example 5

If your COBOL program uses field names that begin with a numeric character, use the NAME directive to assign a different name for use with your database. SQL will typically generate a syntax error when it encounters a column name that begins with a numeric character. For example:

  03  12-months-sales   pic 9(5)V99.

could be renamed this way:

$xfd  name=twelve-months-sales
  03  12-months-sales   pic 9(5)V99.