Incore Database

This document covers the following topics:

• Overview

• Defining Fields of an Incore File

• Identifying an Incore File

• Creating an Incore File

• Manipulating Incore Files with Natural DML

• Managing the Incore Database using the CALLNAT Interface

• The Incore Database Container Data Set

Overview

Traditionally, data processing applications mainly handle fields and files. With the technological advances in the field of data processing, however, the need for manipulating more complex data structures is arising on a large scale. Applications must be able to support the integration of texts, tables, images, graphics, etc.

The Natural ISPF Incore Database facility enables the Natural programmer to maintain complex data structures in the user memory, and to perform complex actions on these structures. Using the Incore Database, you can handle texts, reports, files and tables using the Natural language.

Advantages of Incore Files

Using incore files in application development has several advantages:

• You can integrate Software AG Editor functions in Natural programs, enabling flexible manipulation of your incore files;

• An incore file is a temporary workfile of unlimited space running in memory;

• You can have your personal environment to test and prototype your applications away from your site's database administration activities. After prototyping, no further source changes are required to access a real database;

• If you wish to keep the contents of an incore file permanently, you can write them to a container file. You can retrieve the incore file later, thus avoiding the need to regenerate the data from your programs.

Functions of the Incore Database Facility

The Incore Database facility allows you to perform the following:

• Define an incore file structure using Natural DDMs;

• Dynamically create and delete incore files;

• Manipulate the data in an incore file using the Natural DML or the WRITE reportn statement;

• Invoke the INCORE processor (with CALLNAT interface) to perform operations on an incore file as a whole, for example:

  • BROWSE an incore file (for example, one which contains a report)

  • EDIT an incore file (for example, one which contains text)

  • STORE incore files as a whole into a container file and retrieve them later

Incore database files can be handled like Adabas files with some restrictions on field types, see the subsection Defining Fields of an Incore File. Incore files are not identified by a file number but by an identifier, this allows multiple copies of a file created with the same DDM to be in the database. Incore files are temporary files which cannot be shared by users, each file belongs to only one user. The following figure illustrates this concept:

Incore files are allocated dynamically and stored in memory and, if required, swapped to disk (in fact, the files are stored in the Editor Buffer Pool). Incore files provide "unlimited memory" to a user. The Incore Database can be used in an online environment as well as in Batch. If incore files are to be kept permanently, they can be stored in the CONTAINER (usually an Adabas file) for later retrieval.

Note:
The theoretical maximum for incore files per user is 50. For this reason it is recommended to delete unused incore files, especially when the error message NAT6896 (Session does not exist) occurs.

Defining Fields of an Incore File

You define the fields of an incore file by defining a Natural DDM. This can be done with the Natural utility SYSDDM or with Software AG's data dictionary Predict. In Predict, an incore database is defined exactly as an Adabas database. The DDM is recognized as an incore file by using a special DBID (see the the Natural ISPF Installation documentation or ask your administrator). The file number (FNR) must be a value lower than 191.

Some Information about Fields

• Incore DDMs can include fields of type: Alphanumeric, Numeric, Binary and Packed. Fields can be defined as MU, and can be defined as descriptors. The following types are not supported: Sub, Super, Phonetic and Hyperdescriptors.

• Periodic groups are now supported, but internally handled as a series of multiple value fields and therefore may not themselves contain multiple value fields.

• In addition to these fields, you can define a control pseudo-field (that is, no real database field):

  RN RECORD-NUMBER (N7)

  This field is used to access a physical record number within an incore file.

• The number of fields of an incore file (including multiple occurrences) is limited to 66 (for exceptions to this limitation, see below).

Some Information about Record Size

• The record size of an incore file manipulated using Natural DML or using the CALLNAT INCORE interface (not with CONTAINER actions) is limited to 4000 - n bytes, where n is the number of fields within the file.

• If an incore file is to be stored in / retrieved from the Natural ISPF Container File, its record size is limited to 3896 - n bytes.

• However, you can define and use an incore file with more than 66 fields, if the record size of the file does not require the maximum sizes mentioned above. To be precise, for each additional field over 66, the maximum record size must be decreased by 28 bytes.

• If a view definition contains the pseudo field RECORD-NUMBER, this field can be ignored with respect to the above limitations of record sizes and number of fields.

Identifying an Incore File

Each incore file has an identifier, Format A8. This identifier must be supplied (but can be supplied implicitly) with every Natural statement and incore processor call that refers to the incore file. The identifier notation is:

IDENTIFIER =const/var

If the identifier is omitted, the default is set implicitly by prefix L plus the three-digit FNR. For example, if the incore file to be referenced has file number 12, the default identifier is L012.

Example

The following Natural DML lines read an incore file with identifier PER01 and display fields NAME, AGE, CITY:

....
0080 READ INCORE-PERSONNEL IDENTIFIER = 'PER01'
0090   DISPLAY NAME  AGE CITY
....

The following Natural statements browse an incore file with identifier PER02 using an ISPF-like user interface:

...
0120 MOVE 'BROWSE' TO ACTION
0130 MOVE 'PER02' TO FILE-IDENTIFIER
0140 CALLNAT INCORE USING INCORE-CTL INCORE-DATA
0150 IF ERROR-CODE > 0
....

Creating an Incore File

After an incore DDM has been defined, incore files can be created in several ways:

• Implicitly with the first store statement.

• Explicitly using a CALLNAT interface statement. Using this method, file-internal parameters can be controlled and null files can be created, since no initial STORE is required. This interface is described in more detail in a later subsection.

• By WRITE/DISPLAY report statements. With this mechanism, reports can be stored and manipulated in the incore database.

Creating an Incore File Implicitly

An incore file can be created implicitly with the first STORE statement. The actual record format is then set by the fields that are specified with the STORE statement.

If the file contains multiple value fields or periodic groups, the first STORE statement must specify all occurrences that are to be used with this file. Subsequent STORE statements can specify selected occurrences as long as they do not specify an occurrence greater than the highest occurrence from the first STORE statement.

Example

The Natural DML lines

....
0080 STORE INCORE-PERSONNEL IDENTIFIER = 'PER01'
0090   WITH NAME = 'SMITH'  AGE = 20   CITY = 'NY'
....

create a new incore file with identifier PER01 and fields NAME, AGE, CITY. One record is stored in the file, as specified by the field values.

When creating an incore file implicitly, no additional parameters for creating the file can be defined, the default values will be taken by incore database. If these values are not correct for your type of application or you want to create an empty incore file, you have to create an incore file explicitly.

Creating an Incore File Explicitly

You can create an incore File explicitly using the CALLNAT statement ACTION = 'CREATE'.

The additional parameters are:

Example

The following program displays the NAME, AGE, and CITY data for all personnel whose names begin with S and belong to any department that consists of 5 characters and begins with DEV:

0270 FIND INCORE-PERSONNEL WITH NAME = 'S*'
0280    AND DEPARTMENT ='DEV__'
0290 DISPLAY NAME AGE CITY
0300 END-FIND

The records of an incore file are ordered in a physical sequence. Each record therefore has a physical record number. The record number of a record increases by 1 when a record is inserted before it, or decreases by 1 if a record before it is deleted. In addition to using the ISN, this physical record number can be referred to directly using the DDM pseudo-field RECORD-NUMBER (Adabas short name RN). The sequence of records may be relevant in cases in which the order of records is significant, for example, TEXT lines.

The following table shows the effect of the ISN-TYPE parameter on ISN assignment as well as the usage of *ISN and RECORD-NUMBER in various situations:

Creating an Incore File with a WRITE/DISPLAY Statement

You can direct output to an incore file using the WRITE or DISPLAY statement. The file is then created dynamically.

Example

0010 DEFINE PRINTER(3) OUTPUT 'INCORE'
0020 FORMAT(3) LS=70
0030 READ(100) PERSONNEL
0040 DISPLAY(3) NAME AGE SEX
0050 END

The incore file thus created is assigned the identifier REPORTnn, where nn is the report number (in the above example, REPORT03). The incore file layout will consist of one field, Type Axx, where xx is the report line size (in the above example, A70). The Adabas name of the field is A1. The program IDB-REPO in the example library shows how to read an incore file created by a WRITE / DISPLAY statement.

New reports written to INCORE create new incore files. If a new report is written to an incore file with the same identifier, the 'old' file is overwritten. Once an incore file is created using the DISPLAY or WRITE statement, it can be manipulated as described in the subsection Manipulating Incore Files.

Manipulating Incore Files with Natural DML

Retrieving Incore File Records

Records can be retrieved using any of the Natural statements READ, FIND, GET and HISTOGRAM.

Example

The following lines display the contents of the incore file identified by DOC:

0140 READ TEXT IDENTIFIER = 'DOC'
0150   DISPLAY LINE(AL=70)
0160 END-READ

The following lines display all records as specified by the fields from the incore file identified by the default value (Lxxx, where xxx is the DDM file number).

0270 FIND INCORE-PERSONNEL WITH NAME = 'SMITH'
0280                       AND AGE  > 27
0290   DISPLAY AGE CITY
0300 END-FIND

Note:
READ PHYSICAL, READ BY ISN, READ LOGICAL, FIND SORTED, GET *ISN are all supported. The system variables *NUMBER, *ISN are supported with some restriction in some modes of operation. See the explanation of the ISN-TYPE and INDEX parameters in the subsection Creating an Incore File Explicitly. If the incore file does not exist, the processing loop returns no records and terminates immediately.

Restrictions

• Binary fields may only be used as secondary search criteria, that is, following AND in a FIND, and may not be used at all for logical reads/histograms.

• In a series of nested FIND or READ LOGICAL processing loops, only 2 may refer to the same file identifier.

Adding Records to an Incore File

The stored record is normally added at the end of existing records. However, you can control the physical sequence of the record in a single operation using the pseudo-field RECORD-NUMBER.

Example

The following program writes ten records with the text "Sample text line no: n" to an incore file, and then inserts the text line this is Line Number 5 to Line 5.

0010 DEFINE DATA LOCAL
0020 1 TEXT VIEW OF ISP-IDB-TEXT
0030   2 LINE
0040   2 RECORD-NUMBER
0050 1 I(P3)
0060 END-DEFINE
0070 FOR I = 1 TO 10
0080 COMPRESS 'Sample text line no:'I INTO TEXT.LINE
0090 STORE TEXT
0100 END-FOR
0110 MOVE 'this is Line Number 5'  TO TEXT.LINE
0120 MOVE 5 to TEXT.RECORD-NUMBER
0130 STORE TEXT

Note:
The view TEXT (a file of lines) is a very useful way of maintaining texts in an incore file. The DDM ISP-IDB-TEXT consists of one field: LINE (A80). This DDM is supplied with the Incore Database facility of Natural ISPF.

Modifying Incore File Records

Records in an incore file can be modified using the Natural statements UPDATE, DELETE.

Example

This little program updates an incore file by adding 1 to the value of the AGE field of a specified record.

0270 FIND(1) INCORE-PERSONNEL WITH NAME = 'SMITH'
0280   ADD 1 TO AGE
0290   UPDATE
0300 END-FIND

This program deletes all lines containing the string $TEMP$ from the incore file identified by DOC1:

0270 READ TEXT IDENTIFIER = 'DOC1'
0280   IF LINE = SCAN '$TEMP$'
0290     DELETE
0300   END-IF
0310 END-READ

Managing the Incore Database using the CALLNAT Interface

You can use the CALLNAT interface to create, delete, list, edit and browse incore files. Corresponding subprograms are supplied with the Incore Database component of Natural ISPF.

The subprograms are loaded into libraries SYSISPDB and SYSTEM. If you intend to use Incore Database functionality within your Natural application, make sure that one of the above mentioned libraries is defined as a STEPLIB for your application, or copy all modules for SYSISPDB into one of your STEPLIBs. In addition, you must define library SYSLIBS as steplib for your application.

The parameters for the INCORE subprogram (IDBI--NN) are in a local-data-area: IDBI---L, which contains the following three variables:

The input parameter must be assigned before the CALLNAT is issued. The result will be in the data-area fields after the CALLNAT execution. Available functions for CALLNAT statements to the Incore Database are:

Example

These program lines specify the DELETE function and the incore file identifier EX1 before the CALLNAT is issued:

....
0630 MOVE 'DELETE' TO ACTION
0640 MOVE 'EX1' TO FILE-IDENTIFIER
0650 CALLNAT INCORE USING INCORE-CTL INCORE-DATA
0660 IF ERROR-CODE > 0
....

Deleting an Incore File

You can delete an incore file using a CALLNAT statement with ACTION = 'DELETE' with FILE-IDENTIFIER identifying the incore file to be deleted.

Example

The following lines delete an incore file identified by CURRENT.

0810   ASSIGN ACTION = 'DELETE'
0820   ASSIGN FILE-IDENTIFIER = 'CURRENT'
0830   CALLNAT INCORE USING INCORE-CTL INCORE-DATA
....

Listing Existing Incore Files

You can list all existing incore files using a CALLNAT statement within a REPEAT loop using ACTION = ' '. Search criteria for the parameter FILE-IDENTIFIER is optional. The FILE-IDENTIFIER and NUMBER-OF-RECORDS are retrieved by the subprogram.

END-OF-DATA contains Y after the last call that returns real data.

Example

The following program displays all incore files whose identifiers begin with R:

0900    RESET INCORE-CTL INCORE-DATA
0910    MOVE 'R*' TO INCORE-DATA.FILE-IDENTIFIER
0920    CALLNAT INCORE INCORE-CTL INCORE-DATA
0930    REPEAT UNTIL INCORE-CTL.END-OF-DATA = 'Y'
0940            DISPLAY FILE-IDENTIFIER NUMBER-OF-RECORDS
0950            CALLNAT INCORE INCORE-CTL INCORE-DATA
0960    END-REPEAT

Editing/Browsing an Incore File

The display and modification of an incore file on a terminal screen is not as simple as in the case of a record field manipulation. Sometimes, the data will not fit on a single screen page, so that scrolling capabilities are a requirement.

Additionally, editing requires complex functions such as insert characters, delete characters, order text, find/replace string. The incore facility provides such editing capabilities with a single statement.

Using ACTION='EDIT' or ACTION='BROWSE' on the CALLNAT statement, the incore file is presented using the Software AG Editor. The incore processor does all the terminal input output for you. Once the user has finished modifying or viewing the file, control is returned to your Natural program.

Formatted files that contain several fields can also be edited or browsed. In this case, the fields are delimited with a blank. Physical tabulation is available in edit mode. When in edit mode, only fields of the types Alpha and Numeric are supported (Packed and Binary are not supported). If the file contains binary or packed fields, actions EDIT and BROWSE are handled identically.

Example 1

The following lines start an edit session with the incore file identified by MYDOC:

....
0510 ASSIGN ACTION = 'EDIT'
0520 ASSIGN FILE-IDENTIFIER='MYDOC'
0530 CALLNAT INCORE USING INCORE-CTL INCORE-DATA
....

Incore 1 (data prefixed with 4-digit line number):

  EDIT:-MYDOC------------------------------------------------------------------
  COMMAND==>
  **** ******************************* top of data ****************************
  0001 This is the first line of text
  0002
  0003 It shows an example of an edit session
  **** ************************************************************************
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12-
        Help        Quit        Rfind Rchan Up    Down  Swap  Right Left  Curso

Example 2

The following lines create an incore file dynamically by writing output from the PERSONNEL file to it. The first 100 records from the PERSONNEL file are written to the incore file, which is assigned the default identifier of REPORT03.

....
0010 DEFINE PRINTER(3) OUTPUT 'INCORE'
0020 FORMAT(3) LS=70
0030 READ(100) PERSONNEL
0040    DISPLAY(3) NAME CITY SEX
....

The following lines browse the newly created incore file REPORT03 using the CALLNAT statement.

....
0840  ASSIGN ACTION = 'BROWSE'
0850  ASSIGN FILE-IDENTIFIER = 'REPORT03'
0860  CALLNAT INCORE USING INCORE-CTL INCORE-DATA
....

Incore 2 (no prefixes displayed):

   BROWSE:-REPORT03-------------------------------------------------- Row 1 of 149
   COMMAND==>
   1Page      1                                        93-06-21  09:56:44
  
            NAME                 CITY         S
                                              E
                                              X
    -------------------- -------------------- -
  
    GUENTER              JOIGNY               F
    BRAUN                ST-ETIENNE           M
    CAOUDAL              LE BLANC MESNIL      M
    VERDIE               MILLAU               M
    GUERIN               BOULOGNE BILLANCOURT F
    VAUZELLE             MAMERS               M
    CHAPUIS              IVRY SUR SEINE       M
    MONTASSIER           RENNES               M
    JOUSSELIN            PERPIGNAN            M
    BAILLET              LYS LEZ LANNOY       M
    MARX                 PARIS                M
    D'AGOSTINO           FONTENAY SOUS BOIS   M
    LEROUGE              ARGENTEUIL           M
   Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
         Help        Quit        Rfind Rchan Up    Down  Swap  Right Left  Curso

Additional Parameters when Calling the Editor

When starting a session with the Editor using ACTION='EDIT' or ACTION='BROWSE', some additional parameters can be specified to set up the Editor environment:

MODIFIED (A3) = ['YES']
                ['NO']

This value is returned to the caller when ACTION='EDIT' or ACTION='COMMAND'.

YES means the text has been modified in an edit session.

PREFIXES (A6) = ['NUMS']
                ['CMD']
                ['NONE']

Default: NUMS for ACTION='EDIT'; NONE for ACTION='BROWSE'.

Incore 3 (data prefixed with 2 blanks):

   BROWSE:-REPORT01-------------------------------------------------- Row 1 of 149
   COMMAND==>
      1Page      1                                        93-06-21  09:36:59
  
               NAME                 CITY         S
                                                 E
                                                 X
       -------------------- -------------------- -
  
       GUENTER              JOIGNY               F
       BRAUN                ST-ETIENNE           M
       CAOUDAL              LE BLANC MESNIL      M
       VERDIE               MILLAU               M
       GUERIN               BOULOGNE BILLANCOURT F
       VAUZELLE             MAMERS               M
       CHAPUIS              IVRY SUR SEINE       M
       MONTASSIER           RENNES               M
       JOUSSELIN            PERPIGNAN            M
       BAILLET              LYS LEZ LANNOY       M
       MARX                 PARIS                M
       D'AGOSTINO           FONTENAY SOUS BOIS   M
       LEROUGE              ARGENTEUIL           M
   Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
         Help        Quit        Rfind Rchan Up    Down  Swap  Right Left  Curso

SHOW-COMMAND-LINE (A3) = ['YES']
                         ['NO']
                         ['USR']

Default: YES

Incore 4 (command line not displayed):

   BROWSE:-MYDOC------------------------------------------------------ Row 1 of 12

  

  

  

   This is a sample text line

  

  

  

                                                                                  

TITLE (A50) = ['text']
              ['NO']

Incore 5 (text displayed in top-left corner of screen):

   This is a program-supplied title-----------------------------------------------

   COMMAND==>

   0001 This is a sample text line

  

   **** ***************************** bottom of data *****************************

  

  

  

                                                                                 

MESSAGE (A50) = ['text']

Incore 6 (text displayed in top-right corner of screen).

   This is a program supplied title-------------Please modify text or press PF3!!
   COMMAND==>
   0001 This is a sample text line
   **** ***************************** bottom of data *****************************
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
   Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
         Help        Quit        Rfind Rchan Up    Down  Swap  Right Left  Curso

COMMAND (A50) = ['command']

A valid Editor command, to be executed by the Editor before the edit screen is displayed.

Example

This program starts an edit session with incore file TXT1. The Editor command prompt is not shown, the document name is displayed in the top left corner. When the edit screen is displayed, the cursor will be on the first occurrence of string SUBJECT:

....
0780 ASSIGN ACTION = 'EDIT'
0790 ASSIGN FILE-IDENTIFIER     = 'TXT1
0800 ASSIGN SHOW-COMMAND-LINE   = 'NO'
0810 ASSIGN TITLE =#DOCUMENT-NAME
0820 ASSIGN COMMAND          = 'FIND SUBJECT'
0830 CALLNAT INCORE USING INCORE-CTL INCORE-DATA
....

ALARM (A3) = ['YES']
             ['NO']

Default: NO

SCROLL (A4) = ['CSR']
              ['PAGE']
              ['HALF']

Default: CSR

Other values such as WORD are also allowed, for a full list of valid values, see the Software AG Editor documentation.

HORIZONTAL-SCROLL (A3) = ['YES']
                         ['NO']

Default: NO

HEADER (A80) = ['text']
               ['YES']

If HEADER is empty, the header line will not be displayed. Incore 1 (text displayed above first line of data):

   Top of the Pops - All-time Greats------------------------------------------------
   COMMAND==>
        Title                            Group                No.
   **** ********************** top of data **********************
   0001 I Can't Dance                    Genesis              034
   0002 Steel Wheels                     Rolling Stones       077
   0003 Private Dancer                   Tina Turner          089
   0004 Goodbye Cream                    Cream                118
   0005 Abbey Road                       Beatles              234
   0006 Joshua Tree                      U2                   255
   0007 Thriller                         Michael Jackson      276
   0008 Born in the USA                  Bruce Springsteen    301
   0009 So                               Peter Gabriel        345
   0010 Nightingales and Bombers         Manfr. Mann's Earthb.412
   **** ******************** bottom of data *********************
  
  
  
  
  
  
  
   Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
         Help        Quit        Rfind Rchan Up    Down  Swap  Right Left  Curso

START-HIGHLIGHT-CHAR (A1) = ['char']
END-HIGHLIGHT-CHAR (A1)   = ['char']

Special characters that start and end highlighting of text in a browse screen. Highlighting must be started and ended on one line. The START/END characters themselves are displayed as blanks. An example of highlighted text is given in the figure below.

Incore 2 (highlighted text):

   BROWSE:-MYDOC------------------------------------------------------- Row 1 of 2
   COMMAND==>
   This word is highlighted
   This word is highlighted
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
  
   Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
         Help        Quit        Rfind Rchan Up    Down  Swap  Right Left  Curso

Note that to achieve the highlighting in the above example, each occurrence of "word" must be enclosed in the START/END characters.

Editing in Windowing Mode

Instead of editing in full screen mode, you can display the edit screen in a window and edit in the window.

Example

The DEFINE WINDOW and SET WINDOW statements define the window in which the Editor is displayed:

DEFINE WINDOW WIND1 SIZE 15 * 60   '
              BASE 3 / 10
SET WINDOW 'WIND1'
ASSIGN ACTION = 'EDIT'
....

Incore 3

Enter Incore file Id: DOC1
  
  
  
  
  
            +-------------------------------------------------------------------+
            ! EDIT:-DOC1------------------------------------------------------- !
            ! COMMAND==>                                                        !
            ! **** ************************ top of data *********************** !
            ! 0001 This is a sample text line                                   !
            ! **** ********************** bottom of data ********************** !
            !                                                                   !
            !                                                                   !
            !                                                                   !
            !                                                                   !
            !                                                                   !
            !                                                                   !
            ! Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10- !
            !       HELP        QUIT        RFIND RCHAN UP    DOWN  SWAP  RIGHT !
            +-------------------------------------------------------------------+

A number of more detailed sample programs are delivered on the Natural ISPF installation medium. For a list of their names, issue the command:

HELP EXAMPLE

and scroll down to the heading INCORE DATABASE Examples.

PF Key Handling

The Editor is sensitive to the PF key status, declared in the program. Key position, key display form, key sensitivity and key name can be declared from the program using the SET KEY statement. Keys are translated to Editor commands, using the DATA clause in the SET KEY command.

Example

SET KEY PF7=DATA 'UP 4' NAMED 'Up'
SET KEY PF8=DATA 'DOWN 4' NAMED 'Down'

PF Key Display

The display of the PF key lines when editing/browsing is controlled by the field:

KEYS-TYPE (A8) = {'OFF'}
                 {'ON'}
                 {'DEFAULT'}
                 {'SCREEN'}

Possible values are:

If no key is defined, the Natural ISPF default keys are used.

Assigning Default PF Keys and Language-dependent Constants

A user exit IDB-USRN, distributed in the User Exit Library, can be used to set default PF keys and some language-dependent constants. In order to use this exit you have to copy IDB-USRN to your library and modify it according to your needs.

Escape Commands

After you have edited or browsed an incore file, the QUIT command returns control to the program. However, it is possible to pass escape commands to the Editor. These are commands that, when entered in the edit session, also return control to the program, which then processes the command.

The following parameters can be used on the CALLNAT:

ESCAPE-MAIN-COMMANDS (A120) = {'command1 command2 ...'}
{*}

Passes escape commands to the Editor. Multiple commands must be separated by a blank. The asterisk (*) as value can be used to pass all commands which cannot be processed by the incore processor to the caller.

RETURN- MAIN-COMMAND (A10) = 'token'

When control is returned to the program, the first token of the command is returned in this field.

RETURN-MAIN-COMMAND-PARM (A10) = 'text'

The rest of the command is returned in this field.

Example

The following program starts an edit session with incore file TXT and passes the escape commands CLEAR and ZIP to the Editor.

1120 ASSIGN ACTION ='EDIT'
1130 ASSIGN FILE-IDENTIFIER = 'TXT1'
1140 ASSIGN ESCAPE-MAIN-COMMANDS = 'CLEAR ZIP'
1150 CALLNAT INCORE USING INCORE-DATA INCORE-CTL
1160 DECIDE ON FIRST VALUE OF RETURN-MAIN-COMMAND
1170 VALUE ' '     IGNORE
1180 VALUE 'CLEAR' PERFORM DELETE-TEXT
1190 ESCAPE TOP  /* BACK TOP PROCESS EDIT
.....

Following the same logic, escape line commands can also be used. The available parameters are:

ESCAPE-LINE-COMMANDS (A36) = 'command'

Passes the line command(s) to the Editor.

RETURN-LINE-COMMAND (A2) = 'command'

When an escape line command is entered in the edit session, the program receives the line command in this field.

RETURN-LINE-DATA (A80) = 'data'

When an escape line command is entered in the edit session, the program receives the text in this line in this field.

RETURN-LINE-NUMBER (N7) = 'number'

When an escape line command is entered in the edit session, the program receives the relative line number in this field.

Example

1250 ASSIGN ACTION = 'EDIT'
1260 ASSIGN FILE-IDENTIFIER = 'TXT1' ,
1270 ASSIGN ESCAPE-LINE-COMMANDS = 'TL'
1280 CALLNAT INCORE USING INCORE-DATA INCORE-CTL
1290 DECIDE ON FIRST VALUE OF RETURN-LINE-COMMAND
1300 VALUE ' '  IGNORE
1310 VALUE 'TL
1320 CALLNAT 'TRANSLAT' RETURN-LINE-DATA
1330 FIND(1) TEXT IDENTIFIER = 'TXT1'
1340 WITH RECORD-NUMBER = RETURN-LINE-NUMBER
1350 MOVE RETURN-LINE-DATA TO LINE
1360 UPDATE
....
1450 END-FIND

Resetting the Change Flag

If the contents of an incore file has been saved (stored) in the database and the incore file is not deleted, it could be necessary to mark the incore file as not being modified since the last update of the database. This can be done by using the RESETMOD action. No further parameters are required.

Example

The following program lines specify the RESETMOD function:

....
0440 MOVE 'RESETMOD' TO ACTION
0450 MOVE 'EX1' TO FILE-IDENTIFIER
0460 CALLNAT INCORE USING INCORE-CTL INCORE-DATA
0470 IF ERROR-CODE > 0
....

Editor Commands

All Editor commands are described in detail in the Software AG Editor documentation. The following commands are supported when editing incore files:

Main Commands

Display commands:

BNDS,COLS MASK
CAPS,HEX,NULLS,ADVANCE,ESCAPE,EMPTY,FIX,PROTECT
TABCHAR,TABS,LTAB,
EXCLUDE,INCLUDE,XSWAP
PROFILE,RESET

Position commands:

BOTTOM,TOP,DOWN,UP,LEFT,RIGHT,-H,-P,+H,+P
CURSOR,HOME
LABEL LOCATE,LX,POINT

Text commands:

CHANGE,FIND,RFIND,RCHANGE
DELETE,DX,DY,CX,CY
SHIFT
LC,UC
RENUMBER,UNREN
POWER,ORDER
CENTER,JLEFT,JRIGHT,JUSTIFY
WINDOW,CWINDOW,MWINDOW,DWINDOW

Line Commands:

Positioning:

A,B,O,T

Display:

X,F,L

Text handling:

I,D,R,C,M,W,N
),(,>,<
S,J,UC,LC
BNDS,COLS,MASK,TABS
TF,TC,LJ,RJ,TI,TE
CX,CY,DX,DY,MX,MY,CX-Y,DX-Y,MX-Y,CY-
X,DY-X,MY-X
WS,WM,WC,WM

Issuing Edit Commands using CALLNAT

You can issue an edit command to an incore file using ACTION = 'COMMAND' on the CALLNAT statement to INCORE. With this mechanism program controlled editing can be implemented in an easy way. If the command modified data, YES is returned in the MODIFIED field.

Example

The following lines issue the EDITOR CHANGE command to an incore file identified by REPORT03:

....
0840    ASSIGN ACTION  = 'COMMAND',
0850    ASSIGN FILE-IDENTIFIER = 'REPORT03'
0860    ASSIGN COMMAND = 'Change ATKIN ADKIN all'
0870    CALLNAT INCORE USING INCORE-CTL INCORE-DATA
....

Error Handling

If an error occurs during the execution of the CALLNAT statement, it is returned to the ERROR-CODE and ERROR-TEXT fields.

CALLNAT Parameter Summary

The following matrix provides an overview of which parameters on the CALLNAT statement are relevant to which actions on incore files:

I=Input
O=Output
R=Required

The Incore Database Container Data Set

You can use a "container" data set in which you can store incore files for later retrieval. The container data set itself can be an Adabas or VSAM file. The following figure illustrates the container data set concept:

You can access this container using a CALLNAT statement in the same way as for INCORE, this subprogram is called IDBC---N.

Local data containing the subprogram parameters are supplied in a local-data-area called IDBC---L. The physical container data set is preset using the LFILE parameter (see the Natural ISPF Administration Guide).

END TRANSACTION is not performed by these container accesses, and must be performed by the user program.

Available functions for CALLNAT statements to the container data set are:

An incore file saved in a container data set is identified by means of three fields:

• TYPE (A8)

• GROUP (A48)

• NAME (A32)

Example

The following lines store the incore file identified by PERS in the container data set. The file can later be identified using the values of the TYPE, GROUP and NAME fields:

0510 ASSIGN ACTION          = 'STORE'
0520 ASSIGN FILE-IDENTIFIER = 'PERS'
0530 ASSIGN TYPE            = 'APP1'
0540 ASSIGN GROUP           = 'PERSONS'
0550 ASSIGN NAME            = 'REP001'
0560 CALLNAT CONTAINER USING CONTAINER-CTL CONTAINER-DATA

The following lines retrieve this incore file from the container data set, assigning the identifier PERS1:

0610 ASSIGN ACTION          = 'RETRIEVE'
0620 ASSIGN FILE-IDENTIFIER = 'PERS1'
0630 ASSIGN TYPE            = 'APP1'
0640 ASSIGN GROUP           = 'PERSONS'
0650 ASSIGN NAME            = 'REP001'
0660 CALLNAT CONTAINER USING CONTAINER-CTL CONTAINER-DATA

Lists of files in the container data set can be generated in the same way as listing incore files.

Examples

The following program lists all container entries of type APP1 and group PERSONS:

0760 ASSIGN ACTION          = ' '
0770 ASSIGN TYPE            = 'APP1'
0780 ASSIGN GROUP           = 'PERSONS'
0790 CALLNAT CONTAINER USING CONTAINER-CTL CONTAINER-DATA
0800 REPEAT UNTIL END-OF-DATA = 'Y'
0810   DISPLAY TYPE GROUP NAME
0820   CALLNAT CONTAINER USING CONTAINER-CTL CONTAINER-DATA
0830 END-REPEAT

The following deletes the incore file identified by the TYPE, GROUP and NAME fields from the container data set:

0930 ASSIGN ACTION          = 'DELETE'
0940 ASSIGN TYPE            = 'APP1'
0950 ASSIGN GROUP           = 'PERSONS'
0960 ASSIGN NAME            = 'REP001'
0970 CALLNAT CONTAINER USING CONTAINER-CTL CONTAINER-DATA