Using the DDM Editor

The DDM editor screen (Edit DDM screen) is organized in a table where the field definitions data is contained in rows and columns. All attributes that belong to a field defined for a DDM are contained in one row (that is, source-code line), separated by tabs.

This section describes the columns contained on the DDM Editor screen and the commands provided to create or modify a DDM field, navigate in the screen, or catalog a DDM source, for example.


DDM Header Information

This section describes the fields contained in the header at the top of the Edit DDM screen.

Explanation of DDM Header Fields

Header Field Description
Edit DDM (DDM-type)
The value displayed in parentheses next to the screen title Edit DDM denotes the type of DDM, for example:
   
ADA Adabas
VSAM VSAM
DB2 Db2
DL/I DL/I
PROCESS Entire System Server
CMD-PROC Command processor
SNAT Super Natural
ENTIREDB Entire DB Engine
DBID

The database ID (DBID) as described for DBID in the section DDM Specification.

FNR The number of the file being referenced in the database as described for FNR in the section DDM Specification.
DDM Name The name of the DDM currently contained in the work area of the DDM editor.
Def.Seq.

The default sequence by which the file is read when it is accessed with a READ LOGICAL statement in a Natural program. See also the READ statement described in the Statements documentation.

The default sequence is specified with the two-character field short name. The system validates the short name based on the selected file number. If the database is accessible, the short name is checked against the corresponding field in the database file. If such a field does not exist in the database, a selection list of valid short names is displayed. If the database cannot be accessed, no selection list is generated.

The contents of this field are modifiable.

Columns of Field Attributes

This section describes the field attributes that can be defined in the rows and columns of the Edit DDM screen.

Column Heading Field Attribute
I
The line indicator.

This column displays any of the following letters next to a line:

   
E Line contains an error detected during execution of a CHECK command.
See also CHECK in Editor and System Commands.
   
S Line contains a scanned value.
See also SCAN in Editor and System Commands.
   
X Line is marked for a copy or move operation as described in Line Commands.
   
Y Line is marked for a copy or move operation as described in Line Commands.
T
The type of field:
   
blank Elementary field.
This type of field can hold data and does not contain any other fields.
It can have only one value within a record.
   
C Only applies to a DDM that refers to an Adabas file.
Specifies that a file is physically coupled to this DDM. Files are coupled by using Adabas descriptors.
For further information on file coupling, refer to the Adabas documentation.
   
G Group.
A group is a number of fields defined under one common group name. This allows you to reference several fields collectively by using the group name instead of the names of all the individual fields. Such fields cannot hold any data, but are only containers for other fields.

Note:
Groups defined in a DDM need not necessarily be defined as groups in the Natural object(s) that reference this DDM.

   
M Multiple-value field.
This type of field can have more than one value within a record.
See also Multiple-Value Fields in the Programming Guide.
   
P Periodic group.
A group of fields that can have more than one value within a record.
See also Periodic Groups in the Programming Guide.
   
* Comment line.
L The level number assigned to the field.

Levels are used to indicate the structure and grouping of the field definitions. This is relevant with view definitions, redefinitions and field groups (see the relevant sections in the Programming Guide).

Valid level numbers are 1 - 7.

Level numbers must be specified in consecutive ascending order.

DB

For Adabas files, the DB column displays the two-character short name of the corresponding field in the database file.

For DL/I segment types, the DB column displays the two-character code which is used in DL/I.

For VSAM files, see Natural for VSAM in the Database Management System Interfaces documentation.

For fields of the type C (see the attribute T), this column contains the short name of the Adabas descriptor used for file coupling.

Name The name of the field.

It can be 3 - 32 characters long for Adabas fields and SQL columns, and 1 -19 characters for DL/I names.

When generating a field from an Adabas FDT, the DDM editor assigns a default prefix-FIELD field name, for example, AA-FIELD for DB short name AA, or AUAL-FIELD for short name Aa.

The rules to create a name comply with the naming conventions for user-defined variables (see the Using Natural documentation), except that the first character of the name must always be a Latin capital letter (A - Z). In addition, the name must not start with L@, N@ or O@, where @ is the character with hexadecimal value H'7C'. These prefixes identify indicator fields as explained in the following section.

The field name is the name used in other Natural objects (for example, in a program) to reference the field.

The field name is unique across the whole DDM.

For fields of the type C (see the attribute T), this column contains the short name of the Adabas descriptor used for file coupling.

F The Natural data format of an elementary field, such as A (alphanumeric), P (packed numeric) or L (logical).

For valid Natural data formats, refer to Format and Length of User-Defined Variables in the Programming Guide.

Leng
The standard length of an elementary field.

This length can be overridden by the user in a Natural program.

For numeric fields (Natural data format N), the length is specified as nn.m, where nn is the number of digits before the decimal point an m is the number of digits after the decimal point.

 
In the Leng input field, you can specify either the field length as a numeric value or enter the keyword DYNAMIC to specify that the field length is variable.

For fields of the type C (see the attribute T), this column contains the name of the DDM used for file coupling.

S
Not applicable to VSAM.

Null-value suppression option:

   
blank Indicates that standard Adabas suppression is used; that is, trailing blanks in alphanumeric fields and leading zeros in numeric fields are suppressed.
   
F Indicates that the field is defined with the Adabas fixed storage option; that is, no suppression is used and the field is stored without compression.
   
N Indicates that the field is defined with the Adabas null-value suppression option. This means that null values for the field are not stored in the inverted list and are not returned when the field is used in the WITH clause of a FIND statement, or in a HISTOGRAM or READ LOGICAL statement.

If the Remark column contains NC (not counted), an N in this column indicates that the field is defined with the SQL null-value option. Below this field, the corresponding null-indicator field is listed.

   
M Indicates that the field is defined with the SQL null-value option not null. The Remark field (see Specifying Extended Field Attributes) for this field contains NN NC (not null, not counted). Below this field, the corresponding null-indicator field is listed.
D
The Adabas descriptor type of an elementary field that is not an array.

A descriptor can be used as the basis of a database search performed with the READ or the FIND statement. For example: a field from an Adabas database that has a D or an S in the D column can be used in the BY clause of the READ statement. Once a record has been read from the database using the READ statement, a DISPLAY statement can reference any field that has either a D or an S in this column.

Descriptors types are:
   
blank No descriptor.
This field is not a descriptor.
   
A Indicates that the field is an alternate index for a VSAM file.
   
D Elementary descriptor.
Value lists are created and maintained for this field by Adabas, so that this field can be used as a search criterion in a FIND statement, as a sort key in a FIND statement, or to control logical sequential reading in a READ statement.
   
H Hyperdescriptor.
A hyperdescriptor is a user exit in Adabas. For Natural, it provides the same functionality as a phonetic descriptor (see below).
   
N Non-descriptor.
A non-descriptor is not a descriptor, but can be used as a search field for a non-descriptor search.
   
P Phonetic descriptor.
A phonetic descriptor allows the user to perform a phonetic search on a field (for example, a person's name). A phonetic search results in the return of all values which sound similar to the search value.
   
S Superdescriptor.
If a superdescriptor contains a multiple-value field or a field from a periodic group (or part of such a field), the superdescriptor is marked with an M or a P in the field type column T; this enables Natural to create the correct search algorithms for this superdescriptor.
For a DL/I segment type, S indicates a superdescriptor; that is, a search field of a parent segment.
   
U Subdescriptor or collation descriptor.
If a subdescriptor contains a multiple-value field or a field from a periodic group (or part of such a field), you have to mark the subdescriptor with an M in the field type column T. This enables Natural to create the correct search algorithms for this subdescriptor.
A collation descriptor is used to sort (collate) descriptor field values in a non-standard sequence. If a field is a collation descriptor, the Remark column (see below) reads: Collation, the number of the Adabas user exit that contains the collation sequence (1-8) and the short name of the parent field to which the collation sequence applies, for example, Collation 5 on AA.
   
X Alternate subdescriptor or superdescriptor; that is, an alternate index for a VSAM file.
 
For VSAM files, see Natural for VSAM in the Database Management System Interfaces documentation.

For fields of the type C (see the attribute T), this column contains the name of the DDM used for file coupling.

Remark A comment which applies to a field and/or the DDM.

Indicator Fields

An indicator field is used to retrieve the length of a variable length field or information about the data significance (NULL value indicator) of a database field. An indicator field does not provide the contents of a database field.

A database field name starting with L@, N@ or O@ (where @ is the character with hexadecimal value H'7C') is interpreted as an indicator field. Therefore, a database field name must not start with any of these character strings unless it represents an indicator field.

The following happens when a DDM is initially generated.

  • An L@xxxxx field is automatically added for every variable length field, where xxxxx is the name of the related field.

    This applies to long alpha (LA) and large object (LB) fields in an Adabas file, and VARCHAR and LOB fields in a Db2 table.

    If the length indicator relates to an LA, LB or LOB field, the Natural data format/length must be I4. For a VARCHAR field, the format/length must be I2.

  • An N@xxxxx field is automatically added for a field that may contain a NULL value, where xxxxx is the name of the related field.

    This applies to Adabas fields defined with the SQL Null Value Option and Db2 fields which may have a NULL value by definition. The Natural data format/length of a NULL indicator field must be I2.

  • An O@xxxxx is currently not assigned a particular retrieval function but is reserved for future extension.

    An O@xxxxx is automatically added for a locator field of a Db2 LOB field. The Natural data format/length of a locator field must be I4.

Commands for Editing and Function Execution

This section provides information on the commands provided on the Edit DDM screen.

Line commands are used to copy, delete, insert or move single or multiple source-code lines. Additionally, they are used for invoking the extended field editing function (see Specifying Extended Field Attributes).

Editor or system commands, for example, are used to execute particular line commands, navigate in the DDM source or execute a SYSDDM function directly from the Edit DDM screen.

This section covers the following topics:

Help on Commands

This section provides instructions for obtaining help information on the commands provided on the Edit DDM screen.

Start of instruction setTo display help information on commands

  1. In the command line of the Edit DDM screen, enter HELP.

    Or:
    In the command line of the Edit DDM screen, enter a question mark (?).

    The Editor Help Info screen appears.

  2. Press ENTER to scroll down the help text and to exit the Editor Help Info screen.

    The Edit DDM screen appears.

Line Commands

This section describes all line commands available on the Edit DDM screen and provides instructions for executing a line command.

Start of instruction setTo execute a line command

  1. On the Edit DDM screen, next to the source line(s) to which the command applies, position the cursor in the column T and type in a line command by overriding any existing values in the column T, L, DB or Name.

  2. Press ENTER.

Line Command Explanation
.C(nn) Copies a line once or nn times below the line in which the command was entered.
.CX(nn) Copies the line marked with .X once or nn times below the line in which the command was entered.
.CY(nn) Copies the line marked with .Y once or nn times below the line in which the command was entered.
.CX-Y(nn) Copies a block of lines once or nn times as described in To copy or move a block of lines.
.D(nnnn) Deletes the line in which the command was entered or deletes nnnn lines starting with the line in which the command was entered.

If nnnn is not specified, one line is deleted by default.

.Enn Invokes the extended field attribute editing function as described in Specifying Extended Field Attributes.
.I(nn) Inserts nn blank lines below the line in which the command was entered, where nn can be in the range from 1 to 10. (With the next ENTER, lines that are left blank are eliminated again.)

If nn is not (or not correctly) specified, 10 lines are inserted by default.

To append lines to the source code, use the editor command ADD.

.MX Moves the line marked with .X below the line in which the command was entered.
.MY Moves the line marked with .Y below the line in which the command was entered.
.MX-Y Moves a block of lines as described in To copy or move a block of lines.
.X Marks a single line or the first line of a block of lines to be copied or moved.

A marked line is indicated by an X in the column I.

See also To copy or move a block of lines.

.Y Marks the last line of a block of lines to be copied or moved.

A marked line is indicated by a Y in the column I.

See also To copy or move a block of lines.

Start of instruction setTo copy or move a block of lines

  1. In the first line of the block of lines to be copied or moved, enter the following line command:

    .X

    In the last line of the block of lines to be copied or moved, enter the following line command:

    .Y
  2. Press ENTER.

    The block of lines is delimited as indicated by an X and a Y in the column I.

  3. In the line below which you want to copy or move the marked block, enter one of the following line commands:

    .CX-Y (nn)

    or

    .MX-Y

    where C denotes copy and M denotes move. nn indicates the number of times the marked block is to be copied (if nn is not specified, the block is copied once by default).

  4. Press ENTER.

    The marked block is copied (once or nn times) or moved below the line in which the command was entered.

Editor and System Commands

This section describes the editor commands and Natural system commands available on the Edit DDM screen and lists equivalent PF keys (if relevant).

Start of instruction setTo execute an editor or a system command

  • At the top of the Edit DDM screen, in the command line, enter an editor or a system command.

    Or:
    On the Edit DDM screen, press a PF key if assigned to an editor or system command.

    For example, to catalog a DDM you can either enter the command CATALOG or press PF11.

For an explanation of the symbols used in the syntax diagrams in the following tables, refer to System Command Syntax in the System Commands documentation. An underlined portion of a command denotes a valid abbreviation. Note that the editor commands used to navigate in the DDM source are described in a separate table under Editor Commands for Positioning.

Command Explanation
ADD Appends 10 blank lines to the source code.

(With the next ENTER, lines that are left blank are eliminated again.)

To insert lines, see the line command .I.

CATALOG
Performs a syntax check and saves the DDM source currently contained in the source area as a cataloged object.
CATALOG [ DDM-name ] [ REPLACE ]

If the DDM source has already been cataloged, the REPLACE option must be used.

Equivalent PF key: PF11
CHECK Validates the DDM source in the source area against the Adabas FDT referenced by the DDM.

Should any inconsistency occur, the source line of the field definition that caused the error is marked for correction as indicated by an E in the column I.

Equivalent PF key: PF10
CLEAR Clears the source area as described for the corresponding Natural system command CLEAR in the System Commands documentation.
CODEPAGE Displays the code of the DDM currently in the editor and the session code page. The code page of the DDM currently in the editor may be different to the code page of this DDM on the system file, because a DDM may have been converted during reading it into the DDM editor.
DX Deletes the line marked with the line command .X.
DY Deletes the line marked with the line command .Y.
DX-Y Deletes a block of lines delimited with the line commands .X and .Y.
EX Deletes all lines above the line marked with the line command .X.
EY Deletes all lines below the line marked with the line command .Y.
EX-Y Deletes all lines except for the block of lines delimited with the line commands .X and .Y.
HELP

or

?
Invokes the Editor Help Info screen with help information on editor commands.
LENGTH

or

SIZE

LENGTH
SIZE

[from-field  to-field]
LIST DDM

or

LIST VIEW
LIST

DDM
VIEW

[DDM-name]
Displays a single DDM source or a list of DDMs as specified with DDM-name as described for the corresponding Natural system command LIST in the System Commands documentation.
LOWERCASE

or

LC
Only applies to DDMs of the types A (Adabas) and 2 (Db2 or SQL).

Disables automatic uppercase conversion of lowercase characters. If disabled, Lower ON is displayed in the upper right of the editor screen.

For DDMs that contain lowercase characters, Lower ON is always set when they are opened for editing.

See also UPPERCASE.

QUIT

or

.
Terminates the DDM editor and displays the SYSDDM utility menu. The DDM source is retained in the source area until another source is read into the source area (by any Natural editor) or until the Natural session is terminated.

The DDM editor uses the editor profile option Leave Editor with Unlock to unlock source code when leaving the DDM editor. This option is described in General Defaults in Editor Profile in the section General Information.

Equivalent PF key: PF3
READ
READ [DDM-name]
Reads a DDM source into the source area. Any DDM source currently contained in the source area is overwritten.
RESET Removes all marks from lines marked with an X (see the line command .X), a Y (see the line command .Y) or an E (error during CHECK) indicated in the column I.
SCAN
SCAN [scan-value]
Scans for the search string specified with scan-value, for example:

SCAN ABC or SCAN ABC D.

If found, the line(s) that contain scan-value are marked with an S displayed in the column I. (Press ENTER to remove the marks.)

UNCATALOG
UNCATALOG [DDM-name]
Deletes one or more DDMs from the current FDIC system file if DDM-name is specified (see also DDM Name in the section DDM Specification).

Deletes the DDM source currently contained in the source area if DDM-name is not specified.

This command corresponds to the Natural system command UNCATALOG described in the System Commands documentation.

UPPERCASE

or

UC
Only applies to DDMs of the types A (Adabas) and 2 (Db2 or SQL).

Enables automatic uppercase conversion of lowercase characters. This is the default conversion mode.

See also LOWERCASE.

Editor Commands for Positioning:

Editor Command PF Key Explanation
+

or

+P
PF8

or

ENTER
Scrolls down one page (20 lines).
-

or

-P
PF7 Scrolls up one page (20 lines).
+H PF5 Scrolls down half a page (10 lines).
-H PF4 Scrolls up half a page (10 lines).
X

or

Y
  Positions in the line marked with the line command .X or .Y.
B

or

++
PF9 Scrolls down to the last page.
T

or

--
PF6 Scrolls up to the first page.
+nn   Scrolls down nn lines.
-nn   Scrolls up nn lines.

Specifying Extended Field Attributes

The extended field editing function can be used to specify default field attributes for headers and edit masks, a field comment (remark) and a format option to be applied when the field is used in another Natural object (for example, in a program). In addition, for a DDM generated from a VSAM file you can display and edit VSAM-specific field attributes.

The header attribute specifies the default column header to be displayed above the field when it is output, for example, with a DISPLAY statement. The header corresponds to the text specified with the HD parameter within single quotation marks (HD='text') as described in the Parameter Reference documentation. If no header is specified, the field name is used as column header.

The edit mask attribute specifies the default edit mask to be used when the field is output, for example, with a DISPLAY statement. The edit mask must conform with Natural syntax rules and be valid for the Natural data format and length of the field.

The remark attribute specifies a comment about the field.

The format option can be used to define variable length fields: when set to LA, the field is defined as Long Alpha (LA), when set to LB, the field is defined as Large Object (LOB). A Long Alpha field can be of format A or U, a Large Object field can be of format A, U or B.

Related Topics:

The section below covers the following topic:

Editing Extended Field Attributes

This section provides instructions for invoking and terminating extended field attribute editing for a single field or a range of consecutive fields.

Start of instruction setTo invoke extended field editing

  1. For a single field:

    Next to the field required, position the cursor in the column T column and type in the line command .E over the values in the columns T and L.

    The Extended Field Editing screen for the field marked with the command is displayed as shown in the example of a DDM from Adabas below:

    12:07:49                  ***** Edit DDM (ADA) *****                 2006-02-08
                              - Extended Field Editing -                           
    DDM Name DDM-TEST                          Def.Seq.        DBID     0 FNR   316
                                                                                   
    I T L DB Name                             F       Leng S D                     
    - - - -- -------------- top ------------- - ---------- - -                     
        1 AF LA-FIELD                         A      16381 F                       
    ----------------------------------------------------------                     
                                                                                   
    Remark ........... LA_____________________                                     
    Field Header ..... __________________________________________________          
    Field Edit Mask .. __________________________________________________          
                                                                                   
    Format Option .... LA Long Alpha      (LA = LA field, LB = LOB field)

    On the Extended Field Editing screen, as described earlier, you can specify a remark (comment), a field header, an edit mask and a format option.

    For extended field editing in DDMs from VSAM, see Extended Editing at Field Level in the Natural for VSAM documentation).

  2. For a range of fields:

    1. Next to the first field to be selected, position the cursor in the column T and type in the following line command over the values in the columns T and L:

      .Enn

      where nn is the number of fields to be selected including the current one.

      The Extended Field Editing screen appears for the first field selected.

    2. Enter or modify the field attributes required and press ENTER or PF3.

      The Extended Field Editing screen for the next field in sequence appears.

Start of instruction setTo terminate extended field editing

  • Press ENTER or PF3.

    Any field modifications are saved and the Edit DDM screen appears.