Technical Information

#### Search Results

Search

# Technical Information

This section gives you technical information on how Super Natural processes data. This technical information is intended to help you increase the performance of Super Natural, estimate resource requirements and tells you how to work with certain profile settings.

This section covers the following topics:

- Super Natural and Natural

- Data Selection and Performance

- Sort

- Personal Database

- System Limits

- Error Logging

- DDM Check on Modify

- Status Reports

- RPC Service

- Memory Requirements

- Communication with Other Applications

- The Technical Information Function

- Layout Members

- Passwords and Cipher Code

- User Profile, Option and Adabas Password Hierarchies

## Super Natural and Natural

### Programs

The transaction is the major part of Super Natural. Users define transaction specifications using the menu-driven user interface and Super Naturalgenerates a Natural program from the transaction specification.

The Natural programs generated from Super Natural transactions are saved, cataloged and run by Natural commands like any other Natural program. One of the advantages of this is that Predict Xref data (active cross-references) can be created automatically.

Note
If you use Natural Optimizer Compiler, optimized object code is generated.

In order to generate source code flexibly, Super Natural still generates code with Reporting Mode syntax. This however does not effect performance negatively.

Each Natural program generated from a Super Natural transaction has a block of commentary lines before the source code. The size of the commentary line block depends on the transaction specification.

As opposed to source code which is only relevant at the time of compilation, the block of commentary lines contains all the information necessary for Super Natural about the program which is to be generated and may not be modified under any circumstance.

The Natural ESIZE required for a transaction depends mostly on the number of fields contained in the DDM used. Information on each field contained in the DDM is stored in the ESIZE. The most efficient way of minimizing the ESIZE requirement is to minimize the number of fields in each DDM. The user can also physically remove the fields not needed for a transaction from the source area before running a transaction using the `RELEASE` command. The fields removed are no longer available for that transaction.

### Libraries and Prefixes

The Natural objects which are created (programs in source and object code) are stored in Natural libraries belonging to Super Natural. The names of these libraries are composed of an internal prefix and a library ID. There are three types of Super Natural library which are distinguished for administration purposes by an internal prefix:

- Private
  Belong to one user. The library name consists of an internal prefix and the user ID.

- Public
  Created by the administrator copying objects into them. Only the administrator can copy objects into a public library. Can be used by all those who have the same public library prefix.

- Common
  Can be used by all users. Users can copy objects into a common library. In order to prevent users creating common libraries at will, the administrator must name each common library the user can use.

Within each library the different object types and transaction layouts are distinguished by their individual prefixes. For example, all transactions begin with the prefix `I` (modifiable) followed by the user-defined transaction name and have a layout with the same name but with the prefix `L` (can only be modified in SPPARM during installation).

### Natural Security Considerations

The libraries used by Super Natural need not be defined to Natural Security. This means that you do not have to define all private files both to the application SYSSN and to every Super Natural library. As soon as Super Natural is active, the security profile of the application SYSSN is valid for all Super Natural libraries.

Note
The profile of SYSSN should be set up so that the application is people protected and `Command Mode` is Allowed.

When generating a prototype program or using the Super Natural Report Destination EDITOR, a user could write programs to access all files defined to SYSSN. To prevent this, Natural performs an additional security check of the user's Super Natural profile. If the user is not authorized to access the current file, he receives Natural Security messages.

### System Components

The Super Natural Processor consists of three components:

- Interaction

- Generation

- Execution of program generated

#### Interaction

All user entries are written to the Natural source area or to the side source buffer using Assembler subprograms. Most database access takes place for the following:

- Displaying object lists

- Reading the DDMs used in the transaction

- Displaying system messages and error messages

- Displaying Precict information

- Notepad function

- Values function

- Count function

#### Generation

During generation, processing takes places directly in the source area and all relevant information is read from the internal code table and converted to the relevant Natural notation.

#### Execution

After generation, the execution can be done in conclusion with the generation or as a single command.

The following Super Natural commands can be issued:

- `SAVE`: When the `SAVE` command is issued in Super Natural, the following Natural commands are executed:

  - `RENUMBER`

  - `SAVE`

  - `CATALOG`

- `RUN`: When the `RUN` command is issued in Super Natural, the following Natural commands are executed:

  - `RENUMBER`

  - `SAVE`

  - `CATALOG`

  - `EXECUTE`

- `EXECUTE`: When a transaction is executed from the Transaction list, the following Natural command is executed:

  - `EXECUTE`

    The Natural object is executed but not regenerated, saved and cataloged.

    Note
    If you issue the `EXECUTE` command when the database has been modified since the transaction was run, or if data maintenance has taken place, your results will not be up to date.

- `KEEP`: When the `KEEP` command is issued in Super Natural, the following Natural command is executed:

  - `SAVE`

    Only the transaction specification (commentary lines) is saved and the transaction program is not generated. You cannot execute a transaction having just issued the `KEEP` command.

### DDM Field Names

Do not use Natural key words as field names in DDMs to be used by Super Natural.

### Natural Profile Parameters

It is recommended that all users of Super Natural have the same Natural profile parameters.

If you run a transaction which was created under a different Natural profile to yours, you may receive errors. Problems may occur if, for example the global parameters `Decimal Character` or `Control Character` are different for users of the same common library.

## Data Selection and Performance

`READ` statements take priority over `FIND` statements for database access. Whenever the selection criteria allow, the query is realized using a logical sequential read. The `FIND` statement is only used for complex selection criteria or when a logical sequential read is not possible.

#### Examples:

descriptor>value | Cannot be realized using a logical sequential read and results in a `FIND` statement.
descriptor>=value | Results in a `READ` statement

If you use fields which are not descriptors in a query, post selection using a WHERE clause takes place.

The number of single selection criteria as well as the authorization to use non-descriptors can be determined by the administrator in a user's profile. The administrator can also determine whether a user may read a file physically.

Note
The above does not apply when using `SQL-SELECT` statements.

Post selection in user-defined logical condition statements is realized using the keywords `ACCEPT` and `REJECT`. This means that dependent on the result of a computation, a record which has been read can be either used in further processing or rejected.

### COUNT Function

This function counts the number of records found by the current selection criteria using the `FIND NUMBER` statement where possible. The `FIND NUMBER` statement cannot be used in the following cases:

- if the database management system doesn't allow it

- non-descriptors are used

- for the primary file when files are linked.

### VALUE Function

This function results in a `HISTOGRAM` statement using a descriptor value and can only be used if the data storage system supports it.

### Performance Considerations for Mixed Format Calculation Expressions

#### How to achieve optimum performance when using mixed format expressions:

- Use packed format (P) for business arithmetic. The number of decimal digits in all operands should agree where possible.

- Use floating point format (F) for scientific arithmetic.

- Avoid mixed format expressions. In expressions where formats are mixed between numeric (N, P) and floating point (F), data is converted to floating point format. The conversion between the formats numeric and floating point results in considerable CPU load.

## Sort

Super Natural sorts as follows:

- Database sort (if supported)

  Or:

- External sort or operating system sort.

The database sort is used when a sort using up to three descriptors or a non-descriptor is required.

If a sort using more than three descriptors or a non-descriptor is required, a Natural `SORT` statement is generated. The `SORT` statement initiates an external or operating sort depending on your environment.

A `SORT` statement is also generated if a post selection for the `ACCEPT` and `REJECT` keywords in logical condition statements is required together with system functions. This prevents rejected records being used in control break processing and for the system functions.

The authorization for both types of sort is separate for online and batch processing.

### SORTSZE

Super Natural uses the Natural `SORT` statement when a transaction program is generated to sort the display fields into the order required. Because the memory necessary for this cannot be allocated until the `SORT` statement is performed, run time errors (NAT0910, NAT1202) may occur if the value of the Natural `SORTSZE` parameter is larger than the total memory capacity available.

A minimum value of 10KB (the Natural default value) is sufficient for internal sorts.

## Personal Database

The personal database consists of one or more physical Adabasfiles. Each user works on one file which is determined in his profile. The number of the Adabas file is given to Natural when the user logs on to Super Natural which means that the Natural `LFILE` parameter is not needed.

Each physical Adabas personal database file has a Master DDM which describes how many descriptors and elementary fields of which format and length are available for user files.

The Master DDM describes the following:

- Control field AA

- Numeric descriptors

- Alphanumeric descriptors

- Numeric fields

- Alphanumeric fields

The descriptors identified in the Master DDM are defined with different lengths and the elementary fields are defined with a length of 1. All fields except for AA and CA are defined with null-value suppression.

The physical definition or Field Description Table (FDT) consists of the following:

- Internal control field AA(N8)

- Numeric fields (not in packed format)

- Alphanumeric fields

- Binary superdescriptors

- Alphanumeric superdescriptors

The superdescriptors identified in the FDT consist of the field AA and a descriptor identified in the Master DDM. Because of this, the length of the descriptors in the Master DDM is predefined.

When a user file is created, a DDM is generated according to the user input. All the descriptors required are identified with an Adabas field reference in the Master DDM according to their length. Descriptors in the user file can be shorter but not longer than their counterpart in the Master DDM. All elementary fields are created with the length required as these can be dynamically extended by Adabas.

The non null-value suppressed descriptor `CA` is used to guarantee that all data (including zero information) in a user file can be retrieved. `CA` must be present in every user file. When a Natural program accesses a user file, the Natural descriptor access is converted to access via the corresponding superdescriptor. This means that users can only perform a `READ PHYSICAL` on his own user files using the default descriptor `CA`. This allows data from different user files to be kept separate.

User files can also be processed directly from Natural but the associated DDM may not be modified.

User files are defined as private files in Natural Security and automatically linked to SYSSN. Super Natural users may not use each other's user files unless the administrator authorizes them to. Users and administrators cannot copy transactions with Destination USER FILE.

Because of the interdependency between the DDMs and the data in the personal database, the following conditions must be fulfilled if you want to move them to another physical database:

- The Master DDM must be cataloged with DBID=0

- The Personal Database must have an Adabas file number which can also be used in the new environment

The Personal Database is also used to store Notepad data, runtime error information and information of the DDM Check on Modify functionality.

For an overview of the Personal Database, see the following diagram:

## System Limits

The maximum number of possible field references within Super Natural is 676 per default.

To satisfy special requirements this limit can be enhanced up to 1196 field references by setting the following system option. The limits mentioned, include all fields of a transaction: primary, secondary, lookup, user-defined fields and system variables.

To use the extended number of fields

1. Open the module SPPARM in library SYSSN with the program editor.

2. Switch the option "XL" (extra large number of fields required) on.

       FIELD_REF_XXL='YES'

   Now Super Natural allows to process up to 1196 fields within a transaction.

Note
With this enhancement, the unique Super Natural field references consist of alpha and numeric characters together, for example, A0 --> A9 and 0A -->9Z. This system option is valid for the entire Super Natural system.

## Error Logging

The Error Logging facility allows you to store environment information at the time of your error directly and without a delay.You can use the program SNELOG, stored in the Super Natural library SYSSN, to maintain the logging utility and review runtime errors. Error Logging is designed to report Natural System Errors.

This section covers the following topics:

- Possible Errors

- Listing Error Reports

- Showing Error Reports

- Deleting Error Reports

- Printing Error Reports

- Maintaining Error Reports

- Migrating old Error Reports

If you want to view the Error Logs you have to activate the Error Reporting in SNELOG in the library SYSSN.

### Possible Errors

The following errors are not user errors but may occur for one of the following reasons:

Cause | Cure
--- | ---
System parameters are set too low (SORTSZE, printer size etc.) | Change system parameters
Response codes from DBMS e.g. (NAT3009) | Inform users e.g. using system user exits
Syntax errors due to incorrect Super Natural code generation | Inform Support
System errors due to incorrect Super Natural routines | Inform Support

### Listing Error Reports

If you want to view the Error Reports you have to activate the Service-Routine SNELOG in the Library SYSSN.

Invoke List of Error Reports

- Invoke the Service-Routine SNELOG out of the library SYSSN.

  The following screen appears:

       17:02:54                   ***** Super Natural *****                 2000-06-21
                             - Error Reporting and Analization -              MELOG11

                            Code Function
                            ---- ---------------------------------
                             L   List Error Reports
                             D   Delete Error Reports
                             M   Maintain Error Reporting
                             ?   Help
                             .   Exit
                            ---- ---------------------------------

         Code .............. _
         Library ........... *_______
         Program Name ...... *_______
         Date Time ......... 2000-06-21 *_________
                             YYYY-MM-DD HH:II:SS.T

         Personal DB DBID .. 167__
         Personal DB FNR ... 93___

       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             HELP        Exit                                                  Canc
      4AÂ¦                                                                 14,024

#### Field Descriptions

#### Code

The following function codes are possible:

- `L`: Lists all Error Reports of the according selection criteria, consisting of Library, Program Name and Date / Time.

- `D`: Deletes all Error Reports of the according selection criteria, consisting of Library, Program Name and Date / Time.

- `M`: Maintains Error Reporting.

- `?`: Provides help concerning the Error Reports.

- `.`: Terminates the Function.

#### Library

Choose the library which Error Report you want to display. There are three ways to enter the Library Name:

- Enter the complete Library Name.

- Enter a `*`.

- Enter a part of the Library Name with a Wildcard (*,<,>).

#### Program Name

Choose the transaction whose Error Report you want to display. You can enter the program name as described above.

#### Date Time

Choose a Date / Time to display an Error Report. You can enter the Date / Time as described above.

The List Error Report Screen appears with the set of Error Reports according to your selection.

#### Personal DB DBID / Personal FNR

- Specify the database ID (DBID) and the file number (FNR) of the personal database whose logging list you want to display. The default DBID and FNR depend on the setting of the parameter `LFILE`.

#### List of Error Reports

     17:35:20                   ***** Super Natural *****                 2000-06-21
                                  - List Error Reports -                    MELOG21

     Cmd Date/Time             Err-No Library   Program   Line Stat User-ID
         2000-06-21 *_________  *___  *_______  *_______            *_______
      _  2000-06-21 15:50:23    3055  YPOR      ILIST     0860  O   POR
      _  2000-06-21 16:59:17    0082  YPOR      IERROR    0350  O   POR

     Cmd's are S (Show), D (Delete), P (Print)
     You are on the last page
     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                       Exit              --          +                       Canc

#### Navigation

To move Up / Down

1. Use PF6 to move to the first page.

2. Use PF8 to move one page forward.

To Exit / Cancel

- Choose `Exit` or `Cancel` to leave the transaction list and reach the Error Report main screen.

#### Commands

Choose the required Error Report. There are three ways to process the Error Reports:

- `Show`: The selected Error Report is shown. For further information, see Showing Error Reports.

- `Delete`: The selected Error Report is deleted. For further information, see Deleting Error Reports.

- `Print`: The selected Error Report is printed. For further information, see Printing Error Reports.

#### Field Descriptions

#### Date / Time

Date / Time, when the error occurred and the Error Report is written. You can enter the Date / Time as described above.

#### Error-Number

Shows the number of the error that has occurred. You can enter the Error-Number as described above.

#### Library

Name of the library where the error occurred. You can enter the Library as described above.

#### Program

Program that did flag the error. You can enter the Program name as described above.

#### Line

The line number in the program where the error was identified.

#### Status

Additional information on the kind of error.

#### User-ID

User ID of the person who received the error. This information can be suppressed if desired (see section Maintain Error Reports). You can enter the User ID as described above.

### Showing Error Reports

To show the Error Report

- Enter `S` to show the Error Report.

  A window appears where the most important information concerning the error is displayed.

       17:51:44                   ***** Super Natural *****                 2000-06-21
                                    - Show Error Report -                     MELOG41

       Error occurred at .. 2999-06-21 16:59:17       with UserID ........ POR
       Error Number ....... 7407                      in Library ......... NEWSN
       Error Program ...... SECUB   / Line .. 9540    with Error Status .. O
       Message Text:
         Invalid command, or Subprogram NIX-DA does not exist in library.

       ------------------------- Environment Information ----------------------------

       Device Type ....... PC                 Operating System .. MVS/ESA
                                              TP Monitor ........ COMPLETE
       Product Versions:
         Super Natural ... 9.2.2              System Files (DBID,File):
         Natural ......... 9.2.1                PersonalDB ...... (167,93)
         Predict ......... 8.5.1                FNAT ............ (10,920)
         AOS ............. 0.0.0                FUSER ........... (167,42)
         NSC ............. 9.1.1                FSEC ............ (10,30)
                                                FDIC ............ (167,15)

       You are on the first page
       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                   Print Exit                          +     ++                Canc

#### Navigation

To print

- Enter `Print` (or PF2).

To move Up / Down

1. Use PF6 to page to the first page.

2. Use PF8 to page one page forward.

To Exit / Cancel

- Choose `EXIT` or `CANCEL` to leave the report and reach the Error Report List screen.

#### Error Report Descriptions

#### General Description

     18:20:27                   ***** Super Natural *****                 2000-06-21
                                  - Show Error Report -                     MELOG41

     Error occurred at .. 2000-06-21 16:59:17       with UserID ........ POR
     Error Number ....... 82                        in Library ......... YPOR
     Error Program ...... IERROR   / Line .. 350    with Error Status .. O
     Message Text:
       Invalid command, or Subprogram NIX-DA does not exist in library.

Listing of the major information at the time when the error occurred:

Field | Description
--- | ---
Error occurred at | Date / Time when the error occurred.
Error Number | Error-key
Error Program | Program that did flag the error.
Line | Program line where the error was found.
Message Text | Text, that informs about the error reason.
User ID | User ID that received the error.
Library | Library name where the error occurred.
Error Status | The following entries are possible: C (Command Processing Error) L (Logon Error) O (Object Time Error) S (Non-correctable Syntax error) R (Error on Remote server (in conjunction with Natural RPC)

- Press PF8 for more information.

#### Environment Information

     10:19:19                   ***** Super Natural *****                 2000-09-20
                                  - Show Error Report -                      MELOG41

     Error occurred at .. 2999-07-20 11:45:08       with UserID ........ -
     Error Number ....... 7407                      in Library ......... NEWSN
     Error Program ...... SECUB   / Line .. 9540    with Error Status .. O
     Message Text:
       Program version error.

     ------------------------- Environment Information ----------------------------

     Device Type ....... PC                 Operating System .. MVS/ESA
                                            TP Monitor ........ COMPLETE
     Product Versions:
       Super Natural ... 9.2.2              System Files (DBID,File):
       Natural ......... 9.2.1                PersonalDB ...... (167,93)
       Predict ......... 8.5.1                FNAT ............ (10,920)
       AOS ............. 0.0.0                FUSER ........... (167,42)
       NSC ............. 0.0.0                FSEC ............ (10,30)
                                              FDIC ............ (167,15)

     You are on the first page
     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                 Print Exit                          +     ++                Canc

Default listing of data from the error environment. This list consists of Natural environment variables.

- Press PF8 for more information.

#### Natural Parameter Information

     10:19:19                   ***** Super Natural *****                 2000-09-20
                                  - Show Error Report -                      MELOG41

     Error occurred at .. 2000-07-20 11:45:08       with UserID ........ -
     Error Number ....... 932                       in Library ......... NEWSN
     Error Program ...... SN1110   / Line .. 1510   with Error Status .. O
     Message Text:
       Program version error.

                            Natural Parameter Information (1)

       Term.Control Character (CF) .. ?  65   Limit Error (LE) ............. OFF
       Decimal Character (DC) ....... .  4B   Line Size (LS) ............... 80
       Default Format (FS) .......... ON      Print Mode (PM) .............. RP
       Help Character (HI) .......... ?  6F   Page Size (PS) ............... 23
       Input Assign (IA) ............ =  7E   Structured Mode (SM) .........
       Input Delimiter (ID) ......... ,  6B   Zero Division (ZD) ........... ON
       Input Mode (IM) .............. F       Zero Printing (ZP) ........... ON

     You are on the first page
     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                 Print Exit              --    -     +     ++                Canc

Information of Natural Parameters that are set by starting the session. Some information is displayed additionally in HEX characters. For more information concerning Natural parameters, see the Natural Parameter Reference documentation.

- Press PF8 for more information.

     10:19:19                   ***** Super Natural *****                 2000-09-20
                                  - Show Error Report -                      MELOG41

     Error occurred at .. 2000-07-20 11:45:08       with UserID ........ -
     Error Number ....... 932                       in Library ......... NEWSN
     Error Program ...... SN1110   / Line .. 1510   with Error Status .. O
     Message Text:
       Program version error.

                            Natural Parameter Information (2)

       Max. CPU Time (MT) ........... 6000    Automatic LOGON (AUTO) ....... OFF
       Max. Program Calls (MAXCL) ... 0       Database Updating (DBUPD) .... ON
       Nat. System Commands (NC) .... OFF     Date Format (DTFORM) ......... I
       Wait on Hold (WH) ............ OFF

       Processing Loop Limit (LT) ............ 99999999
       Max. DBMS Calls between IO (MADIO) .... 0
       Read Only System Files (ROSY).......... OFF

     You are on the first page
     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                 Print Exit              --    -     +     ++                Canc

- Press PF8 for more information.

#### Natural System Variables Information

     10:19:19                   ***** Super Natural *****                 2000-09-20
                                  - Show Error Report -                      MELOG41

     Error occurred at .. 2000-07-20 11:45:08       with UserID ........ -
     Error Number ....... 932                       in Library ......... NEWSN
     Error Program ...... SN1110   / Line .. 1510   with Error Status .. O
     Message Text:
       Program version error.

                          Natural System Variables Information

       *DATA .................. 0             *LOG-LS ................ 132
       *HARDCOPY .............. DAEPRTAD      *LOG-PS ................ 23
       *INIT-ID ............... DAEFTCB9      *PAGESIZE .............. 24
       *INIT-PROGRAM .......... NAT31         *PF-KEY ................ ENTR
       *INIT-USER ............. CF            *PF-NAME ...............
       *LANGUAGE .............. 1             *STARTUP ............... MENU
       *LINESIZE .............. 80            *STEPLIB ............... SYSTEM

     You are on the first page
     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                 Print Exit              --    -     +     ++                Canc

- Press PF8 for more information.

#### Natural Stack Information

     10:19:19                   ***** Super Natural *****                 2000-09-20
                                  - Show Error Report -                      MELOG41

     Error occurred at .. 2000-07-20 11:45:08       with UserID ........ -
     Error Number ....... 932                       in Library ......... NEWSN
     Error Program ...... SN1110   / Line .. 1510   with Error Status .. O
     Message Text:
       Program version error.

                                Natural Stack Information

       Stack Level 1:
         Type ...... Stack Empty
         Contents ..
       Stack Level 2:
         Type ...... Stack Empty
         Contents ..
       Stack Level 3:
         Type ...... Stack Empty
         Contents ..

     You are on the last page
     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                 Print Exit              --    -                             Canc

Information on the Natural Stack status.

The Natural parameter information, the Natural system variables and the Natural stack information can be suppressed if desired (see the section Maintain Error Reporting).

### Deleting Error Reports

This command enables you to delete an Error Report.

To delete an Error Report

1. Enter `D` (Delete) beside the transaction name in the list of Error Reports.

   A window appears, where you have to confirm the delete.

   You can also mark multiple Error Reports to delete.

   Or:
   Enter `D` (Delete) within the Error Logging main screen and choose the desired Error Reports out there.

        10:22:11                   ***** Super Natural *****                 2000-09-20
                                     - List Error Reports -                     MELOG21

        Cmd Date/Time             Err-No Library   Program   Line Stat User-ID
            2000*________________  *___  *_______  *_______            *_______
         _  2000-07 !                Confirm Delete                 !  -
         _  2000-07 !                                               !  -
         d  2000-07 !      1 Error Reports will be deleted.         !  -
         _  2000-07 !                                               !  -
         _  2000-07 !       Please enter 'Y' to confirm: Y          !  -
         _  2000-07 !                                               !  -
         _  2000-07 ------------------------------------------------   -
         _  2000-07-20 15:30:26    0932  NEWSN     SN1110    1520  O   -
         _  2000-07-20 16:13:08    0932  NEWSN     SN1110    1520  O   -
         _  2000-07-20 17:07:42    0932  NEWSN     SN1110    1590  O   -
         _  2000-07-21 07:56:15    0261  YCF       T00XX01   0010  S   -
         _  2000-07-21 10:41:07    0932  NEWSN     SN1110    1590  O   -
         _  2000-07-21 10:41:08    0082  SYSSN     SNREST    0000  C   -
         _  2000-07-21 10:41:08    0082  SYSSN     SNREST    0000  C   -
         _  2000-07-21 10:41:08    0082  SYSSN     SNREST    0000  C   -
        Cmd's are S (Show), D (Delete), P (Print)

        Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                          Exit                                                  Canc

2. Enter `Y` if you want to delete the Error Report.

   The Error Report is deleted now.

### Printing Error Reports

This command enables you to print an Error Report.

To print Error Reports

1. Select Error Reports to be printed.

2. Enter `Print` or `PF2`.

   The information of the Error Report is composed on one page and printed on the printer you have choosen.

### Maintaining Error Reports

     18:10:14                   ***** Super Natural *****                 2000-06-21
                               - Maintain Error Reporting -                 MELOG811

                          Code Function
                          ---- ---------------------------
                           E   Enable Error Reporting
                           D   Disable Error Reporting
                           S   Set Error Reporting Options
                           M   Migrate old Error Reports
                           ?   Help
                           .   Exit
                          ---- ---------------------------

                   Code .. _

     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
           HELP        Exit                                                  Canc

These functions help you to maintain the Error Reports. They are described above because the are prerequisites for error logging.

#### Enable Error Reporting

You have to enable Error Reporting in your user file to receive the Error Reports.

To enable Error Reporting

1. Enter `E` and press Enter.

   The following window appears:

        10:31:24                   ***** Super Natural *****                 2000-10-05
                                  - Maintain Error Reporting -                 MELOG811

                    !----------------------------------------------!
                    !                 Enable Error Logging         !
                    !                                              !
                    !  The Error Reporting will be enabled now.    !
                    !                                              !
                    !  Please enter 'Y' to confirm: Y              !
                    !                                              !
                    !----------------------------------------------!
                              .   Exit
                             ---- ---------------------------

                      Code .. E

        Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                          Exit                                                  Canc

2. Enter `Y` and press Enter.

   The Error Reporting facility is enabled

#### Disable Error Reporting

If you do not want to log Error Reports further on, disable this facility. All existing Error Reports are deleted and the future occurring errors are not reported.

To disable Error Reporting

1. Enter `D` and press Enter.

   The following window appears:

        10:27:53                   ***** Super Natural *****                 2000-10-05
                                  - Maintain Error Reporting -                 MELOG811

                   !-----------------------------------------------!
                   !               Disable Error Logging           !
                   !                                               !
                   !   The Error Reporting will be disabled now    !
                   !   and  All Error Reports will be deleted.     !
                   !                                               !
                   !   Please enter 'Y' to confirm: N              !
                   !                                               !
                   !                                               !
                   !-----------------------------------------------!

                      Code .. d

        Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                          Exit                                                  Canc

2. Enter `Y` and press Enter.

   The Error Reporting facility is disabled and all stored Error Reports are deleted.

#### Set Error Reporting Options

This window allows you to specify how Super Natural Errors are reported.

To set Error Reporting options

- Enter `S` and press Enter.

  The following window appears:

                   Set Error Reporting Options

         Online Error Display
           with Error Message Text .......... N  (Y/N)

         Record Error Report Data
           with Natural Session Parameters .. Y  (Y/N)
           with Natural System Variables .... Y  (Y/N)
           with Stack Data/Commands ......... Y  (Y/N)

         Store User ID
           with Error Reports ............... N  (Y/N)

  These options influence the online error messaging and thge date stored in an Error Report as you define them here. You can modify them to your needs. Be aware that the options you set here, concern your whole Super Natural system and are not user-specific.

Online Error Display with Error Message Text:

- Defines if the error is displayed online with message text or just with the error number.

Record Error Report Data with Natural Session Parameters:

- A selected number of Natural session parameters are logged with the values they have at the time when the error occurs.

Record Error Report Data with Natural System Variables:

- A selected number of Natural system variables are logged with the values they have at the time when the error occurs.

Record Error Report Data with Stack Data/Commands:

- The first three levels of stacked data or commands are logged.

For further information on these options, see the following Natural documentation: Installation for z/OS, Installation for VM/CMS and Operations.

#### Store User ID with Error Reports

Defines if the User ID of the user who receives the error is displayed on the Error Report.

### Migrating old Error Reports

If you have Error Reports that are logged by Super Natural versions earlier than 3.3.1, they will not be displayed with the new Error Reporting Facility. You have to migrate them to work with them in future. The old Reports will be structured according to the new Error Reporting facility. After the migration they are available on the List Error Report screen.

To migrate old Error Reports

1. Enter `M` and press Enter.

   The following window appears:

       !--------------------------------------------!
       !                Confirm Migration           !
       !                                            !
       !     211 Error Reports will be migrated     !
       !         to new Error Report Format.        !
       !                                            !
       !  The old Error Reports will be deleted     !
       !  and the old Log File will be closed.      !
       !                                            !
       !  Please enter 'Y' to confirm: y            !
       !--------------------------------------------!

2. Enter `Y`.

   The old Error Reports are migrated. The old Error Reports will be deleted and the old log file will be closed. This means that the Error Reports cannot be viewed with an earlier version of SNELOG if you use a previous version of Super Natural and the current simultaneously.

## DDM Check on Modify

The option DDM Check on Modify allows you, to compare the field structure of the transaction with the current field structure of the DDM used. The result decides wether the current DDM-field structure can be adapted or whether no adaptation is possible.

This section covers the following topics:

- Results of Checking

- Criteria of Checking

- Change of References

- Modes of DDM Check on Modify

- Enable DDM Check on Modify

- Phases of DDM Check on Modify

Furthermore there is the option SNTALOG to obtain a status report, where all information concerning deviations is listed.

### Results of Checking

The following graph shows the order of events of DDM Check on Modify.

Note
DDM Check on Modify is only feasible, if the option DDM Check on Modify is set to "yes". This option can be set in the user-profile, file-profile and superfile-profile.

#### DDMs are unchanged

No deviations are located between the field structure of the transaction and that of the DDM. No Status Report is written and no confirm-window is displayed.

#### Transaction is adaptable

Some deviations are located between the field structure of the transaction and that of the DDM, but they are automatically adaptable. A Status Report is written (if activated) and the confirm-window is displayed.

#### Transaction is not adaptable

Some deviations that are located between the field structure of the transaction and of the DDM, that cannot be adapted automatically. A Status Report is written (if activated) and the confirm-window is displayed.

#### Transaction corrupt, inconsistent or DDM not available

The transaction is detected as corrupt or inconsistent or not all DDMs used are available. A Status Report is written and a confirm-window is displayed.

#### Old Transaction

The transaction cannot be processed, because it was developed with a Super Natural Version before - 311. First the transaction has to be migrated separately without the option DDM Check on Modify. Then it can be adapted. No Status Report is written, but a confirm-window is displayed.

### Criteria of Checking

All transaction that use `Data Selection = Full Screen` or `Data Maintenance Types` (Add, Update etc.) are checked with the option DDM Check on Modify.

Exeption:
Transactions that use other data selection modes ignore the option DDM Check on Modify although they use lookup files.

#### Fields checked

Primary / Secondary Files | All fields of the new DDM are loaded into the transaction. A comparison is made only between the fields of the Transaction and the DDM-Structure that are listed in the worksheet of the transaction. The remaining fields are updated without a DDM-fieldstructure check.
Lookup Files | Only used fields selected in the transaction are loaded from the DDM and compared with the transaction fields.
User Fields | User fields and system variables are only checked to see if the field reference has changed.

#### What Field Properties are Checked?

Fieldname and Filenumber | Criteria of comparison between the new structure of the DDM and the structure of the transaction. Fieldname and filenumber must be identical (primary file must be 1, secondary file must be 2, lookup file must be 3 or higher).Otherwise it is assumed that the field is deleted.
Database-Reference | If the Database-Reference has changed (if it exists) the field cannot be allocated any more.
Format | A change of format is an essential change that can cause errors by processing the transaction.
Level | A change of level indicates that the field is assigned to another group or that is no longer assigned to any group.
Length | If the length decreases, the values that were assigned to that field, may not fit any more.
Decimal-Places | If the length decreases, the values, that were assigned to that field, may not fit any more.
Descriptor Type | A change of the descriptor type indicates that a field obtains a different meaning within the DDM. Possible meanings: Super-Descriptor, Sub-Descriptor, Phonetic-Descriptor or Non-Descriptor.
Array Type | A change of the array type indicates that a field obtains a different occurrence within the DDM. Possible meanings: Array, Multiple, Periodic, Multiple in Periodic, Elementary Field.

### Change of References

#### New Fields in the DDM

If new fields join the DDM, the transaction field-references are moved. All following database fields, system fields and user fields get new references. These changes will be updated automatically in all functions of the transaction.

#### Deleted Fields in the DDM

If fields in a DDM are deleted, transaction field-references are moved. These new references are updated in all functions of the transaction.

### Modes of DDM Check on Modify

A transaction check can lead to the following results:

- no update possible

- automatic update is processed

- transaction is processed without update

### Enable DDM Check on Modify

The option DDM Check on Modify is set in the Maintenance section of Super Natural. The place where the option is set decides the consequences:

user profile | all transactions of this user will be checked
file profile | all transactions of all users, that use this file as primary- or secondary file, will be checked
super-file profile | all transactions will be checked, that use this super-file

The following section describes, how you can proceed a transaction in spite of a changed DDM. However this update is not possible, if a General Error or an Error (see Verification-Level) appears.

### Phases of DDM Check on Modify

The functionality is divided into two phases:

1. Get the current DDM field-structure, compare it against the transaction field-structure and identify differences.

2. Update the references in the functional parts of the transaction. The updated field-list is provided in the worksheet.

#### Update possible

The following window appears:

    +------------------Confirm------------------+
    ! Changes in the data structure of one or   !
    ! more files used in the transaction are    !
    ! detected.                                 !
    !  _ Update Data Structure(s)               !
    !    and Enter Worksheet                    !
    !  _ Leave Transaction                      !
    !                                           !
    +-------------------------------------------+

Proceed the transaction-update

1. Choose the option Update Data Structure(s) and Enter Worksheet.

   The worksheet of the transaction appears.

2. Choose the option Leave Transaction if you do not want to proceed with the transaction now.

   The update of the data structure(s) is canceled. A Status Report (if enabled) is written.

#### Conclude DDM Check on Modify

- If you conclude the transaction with `keep`, `save` or `run` the updated field-description is saved into the transaction.

- If you abandon the transaction with `cancel` or `menu`, the transaction is dropped.

#### No Update possible

No Update is possible if the DDM is changed so, that a system error or an error (see Modify-Options) occurs. The following screen will be displayed.

    +------------------Confirm------------------+
    ! Changes in the data structure of one or   !
    ! more files used in the transaction are    !
    ! detected.                                 !
    ! The differences between the former and    !
    ! the current data structure can not be     !
    ! resolved automatically.                   !
    !                                           !
    !  _ Leave transaction                      !
    !                                           !
    +-------------------------------------------+

To leave the transaction

- Choose Leave Transaction.

  A Status Report (if enabled) is written. It gives the reason for not updating the transaction.

#### Change Transaction Manually to enable the Update

Change Transaction manually to enable the update of the data structure

1. You may switch off the option DDM Check on Modify.

2. Enter the transaction and remove the field usage that prevented the automatic update according the information provided within the Status Report (in enabled).

3. Modify the transaction again with the option DDM Check on Modify.

## Status Reports

This section covers the following topics:

- Displaying Status Reports

- Browsing Status Reports

- Deleting Status Reports

- Printing Status Reports

A Status Report describes the Status of a transaction concerning the changed DDM. For each transaction that was modified using the option DDM Check on Modify, one Status Report is provided. It contains the current status of the transaction and shows finally, whether the transaction was successfully updated and if it was saved with the new DDM field structure.

If you want to view the Status Reports you have to activate the Service-Routine SNTALOG in the Library SYSSN. Further information, see the Installation and Set-Up documentation.

### Displaying Status Reports

You can display the current Status Report out of a list of all available Status Reports.

Invoke List of Status Reports

- Invoke the Service-Routine SNTALOG out of the library SYSSN.

  The following screen appears:

       11:32:21                   ***** Super Natural *****                 1999-04-16
                               - Transaction Status Reports -                 MTALOG11

                            Code Function
                            ---- ---------------------------------
                             L   List Transaction Status Reports
                             D   Delete Transaction Status Reports
                             ?   Help
                             .   Terminate
                            ---- ---------------------------------

         Code .............. L
         Library ........... ypor____  (with library prefix)
         Transaction Name .. I*______  (with transaction prefix)
         Date Time ......... *____________________
                             YYYY-MM-DD HH:II:SS.T

         Personal DB DBID .. 167__
         Personal DB FNR ... 93___

       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             HELP        Exit                                                  Canc

#### Field descriptions

#### Code

The following function codes are possible:

- `L` Lists all Status Reports of the corresponding library.

- `D` Deletes the marked Status Reports.

- `?` Provides help concerning the Status Reports.

- `.` Terminates the function.

#### Library

Enter the library name with the associated prefix. A prefix is always placed in front of the library name. There are three ways to enter the library name:

- Enter the complete library name.

- Enter `*` (the List Transaction Status Report Screen appears where you can choose the appropriate Status Report).

- Enter a part of the library name with a wildcard (*,<,>).

#### Transaction Name

Choose the transaction whose Status Report you want to display. For the way to enter the transaction name see the description above.

#### Date Time

- Choose a Date / Time to display a Status Report. You have three ways to enter the Date / Time:

  - Enter the complete Date / Time (YYYY-MM-DD HH:II:SS.T).

  - Enter `*` (the List Transaction Status Report screen appears where you can choose the appropriate Status Report).

  - Enter a part of the Date / Time with a Wildcard (*,<,>).

#### Personal DB DBID / Personal FNR

- Specify the database ID (DBID) and the file number (FNR) of the personal database whose logging list you want to display. The default DBID and FNR depend on the setting of the parameter `LFILE`.

#### List of Status Reports

     14:05:27                   ***** Super Natural *****                 1999-05-28
                           - List Transaction Status Reports -              MTALOG21

     Cmd Library   Program   Date/Time             Level Status             User-ID
         *_______  *_______  *____________________   *
      _  CSAMPLE   IOTEST03  1999-04-29 14:57:20.0   I   Reference changed  -QE
      _  CSAMPLE   IOTEST05  1999-04-28 17:35:30.4   I   Reference changed  -QE
      _  YCF       IAAAAA    1999-04-30 15:28:46.2   I   Reference changed  CF
      _  YCF       IAAA1     1999-04-23 13:50:15.6   I   Reference changed  CF
      _  YCF       IAAA2     1999-04-23 15:08:43.3   F   Successfully updat CF
      _  YCF       IAAA3     1999-04-23 15:11:17.2   F   Successfully updat CF
      _  YCF       IAAA4     1999-04-23 15:13:13.5   F   Successfully updat CF
      _  YCF       IAABC     1999-04-29 14:37:07.3   W   Length less        CF
      _  YCF       IAAB11    1999-05-03 16:57:17.8   I   Length greater     CF
      _  YCF       IAAB4     1999-04-29 14:37:48.8   F   Successfully updat CF
      _  YCF       IAAB4SEL  1999-04-29 14:41:25.3   F   Successfully updat CF
      _  YCF       IAAB5SEL  1999-05-03 16:56:58.6   E   Not ident.(used)   CF
      _  YCF       IASDF     1999-05-17 11:36:20.6   W   Length less        CF
      _  YCF       INEU3     1999-05-10 13:34:38.4   I   Reference changed  CF
      _  YCF       INEU4     1999-05-10 10:57:45.6   F   Successfully updat CF
     Cmd's are B (Browse), D (Delete), P (Print)

     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                       Exit              --          +                       Canc

#### Navigation

To move Up / Down

1. Use PF6 to move to the first page.

2. Use PF8 to move one page forward.

To Exit / Cancel

- Choose `Exit` or `Cancel` to leave the transaction list and reach the Status Report main screen.

#### Commands

- Choose the required Status Report. There are three ways to process the Status Reports:

  - `Browse`: The selected Status Report is browsed. For further information, see Browsing Status Reports.

  - `Delete`: The selected Status Report is deleted. For further information, see Deleting Status Reports.

  - `Print`: The selected Status Report is printed. For further information, see Printing Status Reports.

#### Field Descriptions

#### Library

Name of the library where the Status Report is stored.

#### Program

Transaction name of the associated Status Report.

#### Date / Time

Date / Time, when the transaction is processed and the Status Report is written.

#### Level

Possible levels: finished, information, warning, error, general error.

#### Status

This field shows detailed information of the reason why the Status Report was written. The worst case is displayed.

#### User-ID

User ID of the person who has processed the transaction.

### Browsing Status Reports

To browse the Status Report

- Enter `B` to browse the Status Report.

  A window appears where the most important information of the processed Transaction with changed DDM is displayed.

       13:40:15                   ***** Super Natural *****                 1999-04-28
                             - Browse Transaction Status Report -             MTALOG31

       Transaction ..... IZ02CRU                  Verified at .. 1999-04-28 13:33:46.7
       Library ......... YPOR                              by .. POR
       Warning ......... Length less
       Primary File .... -QE-TST-21
       Secondary File .. -QE-TST-24

       Cmd Field Verification   Field Name                       Field Type  Format
        _  Length less          START-TIME                       Primary     N 3
        _  Reference changed    ID-YACHT                         Primary     N 8
        _  Reference changed    CHARTER-CRUISE                   Primary     Group
        _  Reference changed    ID-CONTRACT                      Primary     P 6
        _  Reference changed    START-DATE-DESTINATION           Primary     A 49
        _  Reference changed    YACHT-ID                         Secondary   N 8
        _  Reference changed    YACHT-NAME                       Secondary   A 30
        _  Reference changed    YACHT-BRANCH                     Secondary   A 1

       Cmd is S (Show Details)

       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                   Print Exit              --          +                       Canc

#### Navigation

To print

- Enter `Print` and the current Status Report is printed.

  The Status Report is printed.

To move Up / Down

1. Use PF6 to page to the first page.

2. Use PF8 to page one page forward.

To Exit / Cancel

- Choose `Exit` or `Cancel` to leave the transaction list and reach the status report list.

To Show Details

1. Select the field of the transaction you want to get further information about and enter `S` (show details).

   To view multiple fields in detail:

2. Mark the required fields with `S`.

3. Press Enter.

4. Page through the selected field descriptions with PF3.

   After you have paged through all field descriptions, you again reach the browse screen.

#### Status Report Descriptions

#### Transaction

Name of the current transaction with prefix.

#### Library

Name of the library with prefix, where the transaction is saved.

#### Finished / Information / Warning / Error / General Error

Finished / Information / Warning / Error / General Error are possible status of the transaction. This field shows detailed information of the reason why the Status Report was written. The worst case is displayed.

#### Primary File

Name of the primary file

#### Secondary File

Name of the secondary file if defined.

#### Verified at ... by

Date / Time when the transaction was accessed last with the option DDM Check on Modify and user ID, which performed the DDM check.

Note
Further field descriptions see show details.

To view the detailed description of single fields of the transaction

- Enter `S` (show details).

  You receive a detailled description of the choosen field.

Note
You can choose multiple fields simultaneously.

     13:42:14                   ***** Super Natural *****                 1999-04-28
                            - Show Transaction Status Report -              MTALOG41

     Transaction ..... IZ02CRU                  Verified at .. 1999-04-28 13:33:46.7
     Library ......... YPOR                              by .. POR
     Warning ......... Length less
     Primary File .... -QE-TST-21
     Secondary File .. -QE-TST-24

     Detail Information for Field ID-YACHT
       Verification ...... Reference changed                --- In Use with ---
       Field Type ........ Primary                          Link Field
       Format ............ N 8
       Descriptor Type ... Descriptor
       Array Type ........
       Field Reference ... AL
       DB Reference ...... CT
       Linked with File ..

     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
                 Print Exit                                                  Canc

#### Navigation

To print

- Enter `Print`.

  The current Status Report is printed.

To cancel

- Choose `Cancel` to leave the Show Details screen and reach the browse screen immediately.

To exit

- Choose `Exit` to page through the selected field descriptions (if you have chosen multiple fields). After you have paged through the field descriptions, you reach the browse screen.

#### Detail Information for a field

#### Verification

Result of DDM Check on Modify: reason for reporting for a field.

#### File Type

The following entries are possible:

- primary file

- secondary file

- lookup file

- system variable

- dynamic input field

#### Format

Field format and length.

#### Descriptor Type

The following entries are possible:

- empty

- descriptor

- super-descriptor

- sub descriptor

- phonetic descriptor

- hyper descriptor

#### Array Type

The following entries are possible

- empty

- periodic group

- multiple field

- multiple field within a periodic group

#### Field Reference

Unique Reference (two letters) of this field within the transaction. The reference before DDM Check on Modify is shown.

#### DB Reference

Adabas database reference.

#### Linked with File

Filename of the lookup file, which is linked with the current file.

#### In Use with

List of transaction functions where the current field is used.

Possible functions are:

- Display

- Control Break

- Redefinition on Field

- Interfield Arithmetic

- System Function

- Selection

- Calculation

- Logics

- Tabular

- Graphics

- Layout (report)

- User Exit

- Link / Join Field

- Connect Text Link

### Deleting Status Reports

This command enables you to delete a Status Report.

To delete a Status Report

1. Enter `D` (Delete) beside the transaction name in the list of Status Reports.

   A window appears, where you have to confirm the delete.

   You can also mark multiple Status Reports to delete.

       +----------------Confirm Delete-----------------+
       !                                               !
       ! Delete Transaction Status Report IZ02CRU      !
       !                       of library YPOR         !
       ! Please enter 'Y' to confirm: N                !
       !                                               !
       +-----------------------------------------------+

2. Enter `Y` if you want to delete the Status Report.

   The Status Report is deleted now.

### Printing Status Reports

This command enables you to print a Status Report.

To print a Status Report

1. Enter `P` (Print) beside the transaction name in the list of Status Reports.

   A window appears, where you have to confirm printing.

   You have also the possibility to mark multiple Status Reports to print.

       +-----------------Confirm Print-----------------+
       !                                               !
       ! Print Transaction Status Report IZ02CRU       !
       !                      of Library YPOR          !
       ! Please enter 'Y' to confirm: N                !
       !                                               !
       +-----------------------------------------------+

2. Enter `Y`, if you want to print the Status Report.

   The Status Report is printed now.

## Super Natural RPC Service Functionality

This section covers the following topics:

- Introduction

- Hints and Limitations

- Dynamic Input Fields within the RPC Service

- Generate an RPC Service (Server Side)

- Resulting RPC Service Source

- Create the Client Side Parameters

### Introduction

Remote procedure call (RPC) techniques establish a framework for communication between server and client systems that can be collocated on the same computer or based on a network of identical or heterogeneous machines and operating systems. The Natural RPC facility enables a client Natural program to issue a `CALLNAT` statement to invoke a subprogram in a server Natural. The Natural client and server sessions may run on the same or on a different computer.

Natural RPC exploits the advantages of client server computing. In a typical scenario, Natural on a Windows client computer accesses server data (using a middleware layer) from a Natural on a mainframe computer. The following advantages arise from that:

- The end user on the client can use a Natural application with a graphical user interface.

- A large database can be accessed on a mainframe server.

- Network traffic can be minimized when only relevant data are sent from client to server and back.

The RPC service is designed to produceSuper Natural services for distributed working.Super Natural RPC generates a Natural RPC subprogram from a Super Natural Transaction. This NaturalRPC subprogram represents a Naturalobject that is executable in any Natural RPC environment. A Natural RPC service (subprogram) that was generated from Super Natural is executable via a Natural RPC server. The RPC client can be in a network or on a local system and is completely independent.

For further information about RPC, see the Natural Remote Procedure Call (RPC) documentation.

### Hints and Limitations

The following points provide information on the RPC service and show which transactions are not supported:

- Before you can start using the RPC service the administrator has to set it up in the user profile.

- The RPC service is generated in Natural Reporting Mode.

- The RPC service can be used as any Natural RPC service. It contains no Super Natural-specific information.

- For each RPC service generation, the transaction is automatically saved with the Super Natural command `keep`.

- You can only use Report Transactions to generate the RPC service, no Data Maintenance Transactions.

- Transactions, defined with report type `Tabular` are not supported by the RPC services.

- The RPC service Objects are generated to be used with automatic Natural RPC execution. This requires to set the RPC parameter to `AUTORPC=ON`. For further information, see the section Stubs and Automatic RPC Execution in the Natural Remote Procedure Call (RPC) documentation.

- The library type is important to meet the requirements of the RPC logon feature that is set on the client side. For further information, see the section Using the Logon Option in the Natural Remote Procedure Call (RPC) documentation.

### Dynamic Input Fields within the RPC Service

You can process more dynamic RPC services by using the Super Natural dynamic input fields. Herewith the client application defines the selection values at execution time when calling the RPC service.

This requires an additional input structure to be generated for the RPC service. It must be part of the client interface.

### Generate an RPC Service - Server Side

You can use any transaction (except the documented limitations) of your worksheet to proceed the RPC service.

To generate an RPC service

1. Select a transaction out of the transaction list with the `MODIFY` (`mo`) command.

   The worksheet appears.

2. Enter `GENERATE RPC` into the command line.

3. Press Enter.

   The following window with the default settings appears:

                RPC-Service Generation

         The RPC Service will be stored with
             Object Name ........... RPCSMPL1
             in Library ............ NSNSAMPL
             with Generation Mode .. Direct
             and Record Limit ...... 545

           _  Generate with these options
           X  Change options before generation
           _  Modify Transaction

4. Specify how you want to proceed:

   #### Generate with these options

   The generation process starts. If the service object to be generated already exists, confirm the replacement in the appearing window.

   #### Change options before generation

   Modify the RPC service options before starting the generation process. The Modify Generation Options window appears.

   #### Modify Transaction

   Return to the preceding screen to modify the transaction.

5. Select Change Options before Generation.

6. Press Enter.

   The following screen appears:

           RPC-Service - Modify Generation Options

          RPC Service Object Name ........ RPCSMPL1
                      Library ............ NSNSAMPL

          Generation Mode ................ D  Direct
          Limit of Result Records ........ 545____
          (Max. possible Result Records .. 545     )

7. Fill in the required information.

   #### RPC Service Object Name

   Name of the RPC service Object to be generated. Depends on the user options and can be pre-defined by the administrator.

   #### Library

   Library of the RPC service Object to be stored. Depends on the user options and can be pre-defined by the administrator.

   #### Generation Mode

   Direct or Context. Defines how the Generation will be processed. For further information, see the section Generation Modes.

   #### Limit of Result Records / Max. possible Result Records

   Result record handling. For further information, see the section Result Data Limitations.

8. Press Enter.

   The RPC service Object has been generated and is ready to use.

   You can control your RPC service by looking at the Natural-Code.

To confirm the replacement of an RPC service

If you want to generate the same RPC service object twice you have to confirm the replacement of the first.

1. Specify the RPC service Object name in the RPC Options window and press Enter.

   The following window apprears:

        !------------------------------------------!
        !         Confirm Replace RPC Service      !
        !                                          !
        !  The RPC Service RPCSMPL1                !
        !       in Library NSNSAMPL                !
        !  does already exist.                     !
        !  The object will be replaced now.        !
        !                                          !
        !  Enter Y to confirm: Y                   !
        !------------------------------------------!

2. Confirm the replacement by entering `Y` and press Enter.

#### Result Data Limitations

#### Direct Mode

The number and the length of fields are relevant for the number of records!

Example selected result data:

#FIELD - A | N 8
#FIELD - B | A 1
#FIELD - C | A 20
#FIELD - D | A 20

- results in a record length of 49 Byte

- maximal parameter buffer is 30 KByte

- results in a maximal number of 612 records

#### Context Mode

The largest field length is relevant for the number of records in the context area (intermediate storage). The number of records retrieved with one client call has the same limitation as explained in direct mode but multiple calls can be performed in the context mode.

Example selected result data:

#FIELD - A | N 8
#FIELD - B | A 1
#FIELD - C | A 20
#FIELD - D | A 20

- largest field length is 20 Byte

- maximal array size for a field in the context area is 32 KByte

- results in a maximal number of 1638 records

### Resulting RPC Service Source

The following section gives you an insight into the source of a generated RPC service, explains the single sections and introduces the naming conventions for input and output parameters.

#### Overview of the Source

     >                                       > +  Subprogram  RPCSMPL2 Lib NSNSAMPL
     Top    ....+....1....+....2....+....3....+....4....+....5....+....6....+....7..
       0010 * ***************** Super Natural - RPC Service Routine*****************
       0020 *
       0030 * Subprogram: RPCSMPL2
       0040 * Author    : Super Natural
       0050 * Date      : 2000-10-09
       0060 *
       0070 * NSN RPC Identification Area - do not touch the '* NRIA.'-lines below
       0080 * ----------------------------------------------------------------------
       0090 * NRIA. RPC YCF     IA-SMPL2200010091006048200010091001128CF
       0100 * ----------------------------------------------------------------------
       0110 *
       0120 DEFINE DATA PARAMETER
       0130 01 #CONTROL
       0140   02 #RETURN   (N4)
       0150   02 #MORE     (L)
       0160   02 #LIMIT   (N10)
       0170   02 #CT-RES  (N10)
       0180   02 #CT-POS  (N10)
       0190   02 #CT-PAGE  (N5)
       0200   02 #MAX      (N5) 0210 01 #INPUT
       0210 01 #INPUT
       0220   02 #BI_DY_NAME-START (A20)
       0230   02 #BJ_DY_NAME-END (A20)
       0240 01 #OUTPUT (1:V)
       0250   02 #AF_PRI_FIRST-NAME-1 (A20)
       0260   02 #AE_PRI_SURNAME (A20)
       0270   02 #AL_PRI_STREET-NUMBER (A20)
       0280   02 #AN_PRI_ZIP-CODE (A10)
       0290   02 #AO_PRI_CITY (A20)
       0300   02 #AM_PRI_COUNTRY (A3)
       0310 *
       0320     CONTEXT
       0330 01 #AF_CTX (A20/1638)
       0340 01 #AE_CTX (A20/1638)
       0350 01 #AL_CTX (A20/1638)
       0360 01 #AN_CTX (A10/1638)
       0370 01 #AO_CTX (A20/1638)
       0380 01 #AM_CTX (A3/1638)
       0390 END-DEFINE
       0400 *
       0410 SET GLOBALS LE=OFF
       0420 MOVE 1638 TO #CONTROL.#LIMIT
       0430 RESET #LOOP-END(L) #CONTROL.#RETURN
       0440 REPEAT UNTIL #CONTROL.#MORE OR #LOOP-END /* Data retrieval loop
       0450   MOVE TRUE TO #LOOP-END
       0460   RESET #LT-T(P10)
       0470     #CT-OUT(P10)
       0480   #CT-MAX(P7) = 1638
       0490   MOVE #BI_DY_NAME-START TO #BI (A20)
       0500   MOVE #BJ_DY_NAME-END TO #BJ (A20)
       0510   PRI. FIND ( 1639 ) SAG-TOURS-E-PERSON
       0520       WITH SURNAME = #BI THRU #BJ
       0530       SORTED COUNTRY SURNAME
       0540     ADD 1 TO #LT-T
       0550     IF #LT-T > 1638 DO
       0560       MOVE 12 TO #CONTROL.#RETURN
       0570       ESCAPE BOTTOM DOEND
       0580 * Start: Store parameter
       0590     ADD 1 TO #CT-OUT
       0600     IF #CT-OUT GT #CT-MAX DO
       0610       SUBTRACT 1 FROM #CT-OUT
       0620       MOVE 16 TO #CONTROL.#RETURN
       0630       ESCAPE BOTTOM DOEND
       0640     MOVE FIRST-NAME-1(PRI.) TO #AF_CTX(#CT-OUT)
       0650     MOVE SURNAME(PRI.) TO #AE_CTX(#CT-OUT)
       0660     MOVE STREET-NUMBER(PRI.) TO #AL_CTX(#CT-OUT)
       0670     MOVE ZIP-CODE(PRI.) TO #AN_CTX(#CT-OUT)
       0680     MOVE CITY(PRI.) TO #AO_CTX(#CT-OUT)
       0690     MOVE COUNTRY(PRI.) TO #AM_CTX(#CT-OUT)
       0700 * End: Store parameter
       0710   LOOP (PRI.)
       0720 LOOP   /* Data retrieval loop
       0730 IF NOT #CONTROL.#MORE MOVE #CT-OUT TO #CONTROL.#CT-RES
       0740 * Start: Retrieve from context
       0750 RESET #CONTROL.#CT-PAGE #CONTROL.#MORE
       0760 REPEAT
       0770   ADD 1 TO #CONTROL.#CT-POS
       0780   ADD 1 TO #CONTROL.#CT-PAGE
       0790   MOVE #AF_CTX (#CT-POS) TO #AF_PRI_FIRST-NAME-1(#CT-PAGE)
       0800   MOVE #AE_CTX (#CT-POS) TO #AE_PRI_SURNAME(#CT-PAGE)
       0810   MOVE #AL_CTX (#CT-POS) TO #AL_PRI_STREET-NUMBER(#CT-PAGE)
       0820   MOVE #AN_CTX (#CT-POS) TO #AN_PRI_ZIP-CODE(#CT-PAGE)
       0830   MOVE #AO_CTX (#CT-POS) TO #AO_PRI_CITY(#CT-PAGE)
       0840   MOVE #AM_CTX (#CT-POS) TO #AM_PRI_COUNTRY(#CT-PAGE)
       0850   IF #CONTROL.#CT-POS GE #CONTROL.#CT-RES ESCAPE BOTTOM
       0860   IF #CONTROL.#CT-PAGE GE #CONTROL.#MAX DO
       0870     MOVE TRUE TO #CONTROL.#MORE
       0880     ESCAPE BOTTOM DOEND
       0890 LOOP
       0900 * Start: Final Handling
       0910 IF #CONTROL.#RETURN EQ 0 DO
       0920   IF #CONTROL.#CT-RES = 0
       0930   MOVE 8 TO #CONTROL.#RETURN
       0940 DOEND
       0950 * End: Final handling
       0960 END

#### Parameter Structure

#### 1. CONTROL-Structure

#### #RETURN `(output parameter)`

The following return codes are possible:

Return Code | Description
--- | ---
0 | All data is transferred without error.
4 | Buffer of data is transferred without error; more data available. This indicates for the `direct mode` that not all records could be retrieved because of a too small output array definition at the client side or a result set that is larger than the 30 KB limit. This indicates for the `context mode` that more records are available and can be retrieved with a subsequent call.
8 | No data with this selection found.
12 | Record limit is exceeded at the primary file.
14 | Record limit is exceeded at the secondary file.
16 | Result record limit is exceeded. This limit depends on the limitations given by the max. possible result records and the user settings concerning the limit of result records.

#### #MORE `(input and output parameter)`

Flag that shows wether another page can be delivered (`TRUE`) or wether this is the last page (`FALSE`). In direct mode, this parameter is always set to `FALSE` what means that it is not used.

#### #LIMIT `(output parameter)`

Information for the client that indicates how many records can be processed.

#### #CT-RES `(output parameter)`

Result-Counter: Indicates how many records were found with the current selection.

#### #CT-POS `(output parameter)`

Counter-Position: For each page returned, the counter indicates the number of the last record.

#### CT-PAGE `(output parameter)`

Counter-Page: Indicates how many records the current page contains.

#### #MAX `(input parameter)`

Is set by the client application to indicate how many records can be retrieved by the dynamic output array.

#### 2. INPUT-Structure

Input parameters that have to be defined by calling the service. The parameters used by defining the transaction can be taken over into the RPC service. They refer to the dynamic input variables of Super Natural.

#### Naming Conventions of Input Fields

#<unique identifier>_<dynamic field>_<field name>

Example:

    #BI_DY_NAME-START

#### 3. OUTPUT-Structure

Dynamic array. The limit of the array is set by the client. It contains all output fields in the order as selected in the transaction.

#### Naming Conventions of Output Fields

The names for the interface fields are set up with naming conventions as described as follows. Each name can be max. 32 byte.

#<unique identifier>_<field source>_<system function identifier*>_<multiple fields or periodic group identifier*>_<field name>

* if used in the transaction

Part of the Name | Description
--- | ---
Unique Identifier | Super Natural Field Reference
Field Source | Possibilities: primary file (PRI) secondary file (SEC) lookup file (F) user field (U) work file field (U) dynamic variable (U) system variable (S)
System Function Identifier | Appears only in Summary mode.
Multiple Fields and / or Periodic Group Identifier | Appears only for database arrays.
Field Name | Name of the field used.

Example:

    #AY_PRI_MAX_P2M2_BONUS

Periodic groups and multiple fields are flatterned for the RPC service for performance purposes as follows:

leads to

#### Overview of the Modes and Options

#### Generation Modes

Direct Generation Mode | Context Generation Mode
--- | ---
Returns all result data with one call. | Returns the result data with multiple calls (where conversational RPC mode is required).
The result data amount is limited to 30 KByte (general limitation for Natural subprogram parameters). For an example see section RPC result data. | The result data amount is limited to 32 KByte for every field (general limitation for Natural arrays). Occurrences of an output array are treated as single fields. As the result data is organized in output records, the largest field of the record defines the number of records of the result data. The result data retrieved with one call is limited to 30KByte. For an example see section RPC result data.
All result data is immediately available for the client. This enables the usage of the RPC service in local environments for example testing requirements. | The result data is stored in the RPC-specific context area and can be retrieved buffer by buffer to the client. No local use of the RPC service is possible.

#### Record Limit

The Record Limit informs you about the maximum possible number of records that can be retrieved by the RPC service. This depends on the generation mode, the used transaction, possibliy used summary mode and the largest field used in the output data. For an example see section RPC result data.

#### Generation Modes and PRC Conversation Modes

The following table gives you an overview of the Generation Modes and the possible RPC modes. For further information, see the Natural Remote Procedure Call (RPC) documentation.

| Direct Generation Mode | Context Generation Mode
--- | --- | ---
Conversational RPC | Not required for the RPC service itself. It may be recommended if the Super Natural PRC service is part of a set of RPC services to be executed together. | Required for the PRC service to hold the conversation until all data buffers are received by the client.
Non-Conversational RPC | Recommended if the RPC service is executed as a single. | Not recommended as only the first data buffer can be received by the client. The others will be lost because the conversation is not hold.

### Create the Client Side Parameters

The client side parameter structure can be created easily by using the RPC service and the Natural local data area editor as follows:

To create the client side parameters

1. Open the Natural local data area editor by entering the following command: `edit l`.

2. Enter in the first editor line the line command `.i <(your object name)>`.

3. Press Enter.

   The following window appears:

        NAT0082 Invalid command, or object NSN-RPC does not exist in library.
        Local               Library EXCEL                          DBID   167 FNR    32
        Command                                                                     > +
        I T L Name                             F Leng Index/Init/EM/Name/Comment
        All - -------------------------------- - ---- ---------------------------------
          . i (r-context>!--------------------------------------------------!
                         !                Data Area Editor                  !
                         !                                                  !
                         !                                                  !
                         !     Please select :                              !
                         !                                                  !
                         !    _  All local variables and parameters         !
                         !    _  All local variables                        !
                         !    _  Only internally defined local variables    !
                         !    _  All parameters                             !
                         !    _  Only internally defined parameters         !
                         !                                                  !
                         !--------------------------------------------------!

        ----------------------------------------------------------------- S 0    L 1

4. Select All Parameters.

5. Press Enter.

   The parameters are separated from the coding.

6. Save them as a local data area.

7. Export them to the client environment.

Note
Before stowing the local data area, the dynamic `#OUTPUT` array must be defined by a concrete value.

## Memory Requirements

Super Natural is a Natural application and as such follows the Natural recommendations for applications. However, because Super Natural generates programs, it is advisable that you follow the recommendations below when setting your session parameters:

Buffer | Size
--- | ---
DATSIZE | 50
ESIZE * | 45
RUNSIZE | 20

`* ESIZE` is dependent on the size of the DDMs you are dealing with and the number of fields used. Some transactions may need larger values than those listed above.

#### Example

The sample transaction SAMPLE2 described in the section Sample Transactions in the User's Guide has the following transaction specification:

Primary File | SAG-TOURS-E-CRUISE
Display Fields | 1A: START-DATE 1B: END-DATE 2: CRUISE-PRICE 3: CRUISE-ID 4: START-HARBOR 5: DESTINATION-HARBOR 6: CHARTER-YACHT-TYPE
Control Fields | 1: START-DATE
System Function | Minimum on field CRUISE-PRICE
Sort Field | 1: START-HARBOR
Selection Criteria | AT GE 500

The transaction results in the following sizes:

ESIZE | 6608 Bytes
DATSIZE | 612 Bytes
Buffer Pool | 2684 Bytes

#### Example

The sample transaction SAMPLE3 described in the section Sample Transactions in the User's Guide has the following transaction specification:

Primary File | SAG-TOURS-E-CRUISE
User Fields | MY-START-DATE MY-START-YEAR MY-START-MONTH MY-START-DAY MY-END-DATE MY-END-YEAR MY-END-MONTH MY-END-DAY
Display Fields | 1: CRUISE-ID 2: START-HARBOR 3: DESTINATION-HARBOR 4A: MY-START-DATE 4B: MY-END-DATE
Selection Criteria | CHARTER-YACHT-TYPE = 'ATLANTIC 29'
Calculation Statement | MY-START-DATE=MY-START-DAY!'.'!MY-START-MONTH!'.'!MY-START-YEAR MY-END-DATE=MY-END-DAY!'.'!MY-END-MONTH!'.'!MY-END-YEAR
Logical Conditions Statement | 1 I < START-DATE GT 19910701 1 T < MY-START-DATE = 'TOO LATE 1 T < MY-END-DATE = ' '

The transaction results in the following sizes:

ESIZE | 8325 Bytes
DATSIZE | 564 Bytes
Buffer Pool | 2392 Bytes

## Communication with Other Applications

Super Natural can be invoked from any other Natural application and you can invoke any other Natural application from it.

When Super Natural is invoked from another application, you can ensure that you are returned to it when exiting Super Natural by using the Natural `SETUP` command because Super Natural always terminates with the `RETURN` command.

Every application which is invoked from Super Natural must terminate with the `RETURN` command to ensure that Super Natural is reactivated.

## The Technical Information Function

The `Technical Information` function provides you with technical information concerning your environment as in the following example:

     18:01                      ***** SUPER NATURAL *****                 2999-04-28
                                       - Main Menu -                          SN1000

             +------------------------Technical Information------------------------+
             ! NSN Version ......... 9.2.2            Operating System .. MVS/ESA  !
             ! PersonalDB-File ..... (167,93)         TP Monitor ........ COMPLETE !
             !                                        Device Type ....... COLOR    !
             ! Natural Version ..... 9.2.1                                         !
             ! PREDICT Version ..... 8.5.1            AOS Version ....... 0.0.0    !
             !                                        NSC Version ....... 9.1.1    !
             !                                                                     !
             ! Buffer Sizes:   Esize ..     k  DATsize ...    k  Usize ..    k     !
             !                 Fsize ..     k  SORTsize ..    k  Csize .. 20 k     !
             !                                                                     !
             ! Last Error Number ... 1                                             !
             ! Last Error Program ..                  Last Error Line ...          !
             !                                                                     !
             ! Program: ________ was cataloged at                                  !
             !                                                                     !
             +---------------------------------------------------------------------+
     Command ===>

     Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
           Help        Exit              Flip                                Canc

If you phone Customer Support because an error has occurred, you may be asked to enter a Super Natural module number in the Program field to obtain cataloging information.

The Technical Information function is always available.

## Layout Members

When you save, run or execute a transaction, a copy code layout member is created with the name layout-prefix transaction-name. When you keep a transaction, a layout member with dummy copy code is created. Before you have kept, saved or run a transaction, the name transaction-name is reserved for its layout member. You only see the work-in-progress layout name in exceptional cases (after power cut etc.).

## Passwords and Cipher Code

If Adabas security is being used, passwords or cipher codes can be set either for users or for files in the Super Natural Administration application. The passwords and cipher codes are read from the user profile each time a transaction is modified. Because this does not take place at run time, security errors caused by password changes may occur if a transaction is not regenerated.

## User Profile, Option and Adabas Password Hierarchies

### User Profile Hierarchy

The administrator defines which files a user may use and specifies settings for profile, layout and options. The user can modify certain options and defaults from the Modify Profile screen in Super Natural Processor. The user can only modify options he is authorized to use. The user-defined profile overrides the profile set by the administrator. The user can also override his own user-defined profile just for the current transaction using the `OPTIONS` and `MODES` commands.

### Option Hierarchy

Options set for a file in the file profile override options set for a file in a user profile.

When you add (link) a file to Super Natural, the file has no option settings and no user list. The individual file settings which are part of each user profile are valid for users when accessing this file if you leave the options settings and/or the user list blank.

### Adabas Password Hierarchies

Adabas passwords control file access. The hierarchy of Adabas passwords is as follows:

Passwords on upper levels have priority and are used if provided.

When an Adabas password is provided, it is generated for each transaction program or prototype program (except for those which access user files) as a Natural `PASSWORD` statement. When a program containing a `PASSWORD` clause is modified, the password entry that is active at modification time is used.

Adabas passwords and cipher codes affect existing transactions.

### On this page

- Super Natural and Natural
- Data Selection and Performance
- Sort
- Personal Database
- System Limits
- Error Logging
- DDM Check on Modify
- Status Reports
- Super Natural RPC Service Functionality
- Memory Requirements
- Communication with Other Applications
- The Technical Information Function
- Layout Members
- Passwords and Cipher Code
- User Profile, Option and Adabas Password Hierarchies