Natural Text Modules and Macros

#### Search Results

Search

# Natural Text Modules and Macros

This document describes the Natural text modules `NATTEXT`, `NATTXT2`, `NATTXT2U`, `NATTXT3` and the Natural macro `NTERMSG`.

- Function and Usage of Text Modules

- NATTEXT - Natural Keyword Definitions

- NATTXT2 - Output Text, Keywords and User Termination Messages (Mixed Case)

- NATTXT2U - Output Text, Keywords and User Termination Messages (Uppercase)

- NATTXT3 - Text Fragments for Placeholders in Natural Error Messages

- NTERMSG - Natural Termination Messages and Return Codes

## Function and Usage of Text Modules

All Natural keywords, alternative keywords and standard output text are contained in the modules `NATTEXT` and `NATTXT2`. Natural system commands and alternate system commands are also included as keywords and alternative keywords in these modules. Substitution text fragments for Natural error messages are contained in module `NATTXT3`. The modules are contained in source form in the Natural source library and in load module form in the Natural load library.

If necessary, you can modify Natural keywords, alternative keywords and text contained in these modules. For example, Natural session termination messages can be changed from English to another language, Natural keywords can be disabled, or synonyms can be added.

If any modifications are made to a `NATTEXT`, `NATTXT2` or `NATTXT3` module, each modified module must be assembled, link-edited and included into the executable Natural module; refer to the corresponding Natural installation documentation.

## NATTEXT - Natural Keyword Definitions

The `NATTEXT` module contains the macros `NTKEY`, `NTALT` and `NTSYN` for each keyword and alternative keyword to be recognized by Natural.

### Modifying NATTEXT

| Warning: It is recommended that you modify the `NATTEXT` module for very important reasons only, because once modified, it can no longer be properly maintained by Software AG personnel.

The following rules apply:

- A keyword value for a `NTKEY` or `NTALT` macro can be changed by replacing the current keyword value with the desired value.

- A keyword or alternative keyword can be disabled by replacing the keyword value with the character "%".

- The position of each `NTKEY` and `NTALT` macro within the module is fixed and must not be shifted. Additional `NTKEY` and `NTALT` macros must not be inserted.

- Synonyms can be assigned for any keyword or alternative keyword using the `NTSYN` macro. One or more `NTSYN` macros can be inserted after a `NTKEY` or `NTALT` macro. The `NTSYN` macro includes one parameter, which is the value to be used as the synonym. If the synonym contains embedded blanks, the entire value must be enclosed in apostrophes.

### Example of Modifying the NATTEXT Module

The following example illustrates how a `NATTEXT` module is modified. In this example

- the synonym `RECHERCHE` is to be used for the keyword `FIND`;

- the synonym `LISEZ` is to be used for the alternative keyword `BROWSE`;

- the keywords `GET` and `HISTOGRAM` are to be disabled.

`NATTEXT` before modification:
    STATNAM NTKEY FIND
            NTALT BROWSE
            NTALT GET
            NTALT ACCEPT
            NTALT REJECT
            NTALT HISTOGRAM
`NATTEXT` after modification:
    STATNAM NTKEY FIND
            NTSYN RECHERCHE
            NTALT BROWSE
            NTSYN LISEZ
            NTALT %
            NTALT ACCEPT
            NTALT REJECT
            NTALT %

## NATTXT2 - Output Text, Keywords and User Termination Messages (Mixed Case)

The `NATTXT2` module contains the macros `NTKEYT`, `NTALTT` and `NTSYNT` which define the following:

- Standard Natural Output Texts

- Keywords and Alternative Keywords for Natural System Commands and Utilities

- User-Written Termination Messages

### Standard Natural Output Texts

The module `NATTXT2` contains the following standard Natural output texts, each of which can also be displayed in another language if the language code is set accordingly (see also below):

- the literal `Page` used in the standard output page header;

- the name of each month as used in the Natural system variable `*DATG` (Gregorian date), date edit masks (L), and the name of each day as used in date edit masks (N);

- the `ENTER INPUT DATA` message and the skeleton error messages for error numbers 1104, 1105 and 1106 (used during online input processing);

- the error message used for system file open failure (which cannot be retrieved from the system file); an error number of the form `NAT8xxx` (where xxx is the decimal Adabas response code) is added to this error message by Natural;

- the constants `More`, `Top` and `Bottom` used in windows for position information to be displayed in text form;

- the table to define reports and report handling for reports greater than 33.

Any values contained in `NATTXT2` can be modified by replacing the current text with the desired text. If a month-name synonym exceeds nine characters, only the first nine positions are used by the system variable `*DATG`.

`NTSYNT` macro statements can be added as described for module `NATTEXT`. However, with `NATTXT2`, a second parameter can be specified. This parameter is optional and represents the language indicator to be used for the synonym. When you specify the language indicator, Natural produces message output resulting from the use of this synonym in the corresponding language. In addition, if error message texts have been stored in the Natural system file using a language indicator other than `1` (which is the default and stands for `English`), error messages are returned in the corresponding language. For information on which language code stands for which language, refer to the profile parameter `ULANG`.

### Keywords and Alternative Keywords for Natural System Commands and Utilities

The module `NATTXT2` contains `NTKEYT` and `NTALTT` macros for each keyword and alternative keyword to be recognized by Natural for the following Natural system commands and utilities, parameters of commands and their values when applicable. Each of these can also be used in another language if the language code is set accordingly (see also below):

- all Natural system commands in general;

- for the `GLOBALS` system command, the parameters and their values when applicable;

- for the `COMPOPT` system command, the parameters and their values when applicable;

- public system commands (these system commands are permanently valid and cannot be disallowed, neither by means of Natural Security nor by the Natural profile parameter `NC`;

- Natural utilities

The `NTKEYT` and `NTALTT` macro statements can be used similar to the `NTKEY` and `NTALT` macro statements as described for module `NATTEXT`.

The `NTSYNT` macro statements can be used as described under Standard Natural Output Texts.

### User-Written Termination Messages

User-written termination messages can be added with the macro `NTERMSG` for all return codes (`1 - 255`) which can be issued with a `TERMINATE` statement and which normally lead to the Natural termination message NAT9987.

You specify the termination message text with the first parameter, and the corresponding return code with the second parameter.

#### Example:

    NTERMSG 'USR0077 THIS IS A SAMPLE USER MESSAGE FOR RETURN CODE 77',77

A `TERMINATE 77` statement in a Natural application will result in the following termination message: `USR0077 THIS IS A SAMPLE USER MESSAGE FOR RETURN CODE 77`.

## NATTXT2U - Output Text, Keywords and User Termination Messages (Uppercase)

The `NATTXT2U` module contains the same items as the `NATTXT2` module. The difference is that certain keywords for the English language are contained in mixed case in `NATTXT2` whereas they are in all uppercase in `NATTXT2U`. This affects the keywords `MORE`, `TOP`, `BOTTOM`, `PAGE`, and all month and weekday names.

`NATTXT2U` should be linked to the Natural nucleus instead of `NATTXT2` in environments where lower-case code points `H'81'` to `H'A9'` are used to display national characters, for example, if code page 930 with half-width Katakana characters is used.

## NATTXT3 - Text Fragments for Placeholders in Natural Error Messages

The `NATTXT3` module contains the macros to define the text fragments which will be used to substitute the :n: place holder in Natural error messages.

Each text fragment can be defined in various languages. For information on which language code stands for which language, refer to the `ULANG` parameter.

The text fragments will be generated in EBCDIC and Unicode notation.

Note
To assemble the `NATTXT3` module, a high level assembler must be used which supports the macro function `UPPER` and the definition of Unicode characters (`DC CU’unicode text’`).

Example:

The text for Natural error NAT0082 (when trying to execute a non existing program) looks as follows:

    Invalid command, or :1: :2: does not exist in library.

Trying to execute the object `NOTEXIST` leads to following result:

    NAT0082 Invalid command, or Program NOTEXIST does not exist in library.

`:2:` was replaced by the object name (`NOTEXIST`).

`:1:` was replaced by the text fragment `Program`.

The text fragment was declared in module `NATTXT3` as follows:

    *===============================================================
    *              PROGRAM                  0002
    *===============================================================
          MSGSDEF  &LC_PGM
             SPACE
    *---------------------------------------------------------------
          MSGSLAN  01,Program           1   ENGLISH
          MSGSLAN  02,Programm          2   GERMAN
          MSGSLAN  03,programme         3   FRENCH
          MSGSLAN  04,programa          4   SPANISH
             SPACE
    *---------------------------------------------------------------
          MSGSGEN

Text fragment values for additional languages may be entered by adding further `MSGSLAN` macros.

## NTERMSG - Natural Termination Messages and Return Codes

Natural has a number of standard session termination messages (NAT99...) that are delivered in macro `NTERMSG` and can be modified there (for example, to translate them it into another language). The overall length of ID and text can be up to 72 characters. After the macro `NTERMSG` has been modified, the Natural parameter module has to be re-assembled and linked.

Apart from the message ID and text, each standard termination message also includes one of the following Natural system return codes, which are also defined within macro `NTERMSG`:

Code | Explanation
--- | ---
`0` | Normal termination.
`4` | Error occurred during execution/compilation (batch mode only).
`8` | Termination due to severe runtime error.
`12` | Session initialization failure.
`16` | Abnormal termination due to abend or severe environment failure..

With the profile parameter `TS` set to `ON`, the termination messages are translated to upper case using the upper case translation table `NTUTAB1` as supplied in the `NATCONFG` module before they are displayed.

In addition to `TS=ON`, further parameters to provide for translation of messages into upper case are provided by several Natural components. For further information, see Other Parameters to Provide Upper Case Translation in the `TS` profile parameter description.

### On this page

- Function and Usage of Text Modules
- NATTEXT - Natural Keyword Definitions
- NATTXT2 - Output Text, Keywords and User Termination Messages (Mixed Case)
- NATTXT2U - Output Text, Keywords and User Termination Messages (Uppercase)
- NATTXT3 - Text Fragments for Placeholders in Natural Error Messages
- NTERMSG - Natural Termination Messages and Return Codes