Useful Features

#### Search Results

Search

# Useful Features

This document describes special features that make work with Natural more comfortable. There are three categories of special features:

- Handling and Navigational Features

- Functional Features

- Additional Features in Lists

The lists below present these features at a glance.

These features are described in more detail in the following subsections. For special features concerning command input, see section Command Logic.

## Handling and Navigational Features

The following topics are covered below:

- Working in Split-Screen Mode

- Multi-Session Operations

- Selecting a Function or Object

- ENTRY as Line Command

- Cursor-Sensitive String Selection - :C Directive

- Automatic Transfer of Commands

- Command Redisplay Feature

- Editor Sessions

- Editor Session with No Prefix

- Online Help Facility

- Online Technical and Site-Specific Information

- Confirmation Windows

- Using the Trace Function

- Break in Processing

- Automatic Screen Refresh

### Working in Split-Screen Mode

Working with Natural in split-screen mode means dividing your screen horizontally into two sections and running a Natural session in each section.

You split your screen at the cursor position using the `SPLIT` session command (usually assigned to PF2). Alternatively, you can issue the `SPLIT` command with a line number as parameter. Your screen is then split at the specified line. If you only had one Natural session, another is automatically opened. If you had several sessions, the session last suspended is recalled to display.

You can change the portion of the screen devoted to each session by moving the cursor to where you wish to split the screen and repeating the `SPLIT` command.

The split-screen feature is useful for easy control of parallel sessions. For example, you could run a Natural program from an edit session in one screen session and immediately see the resulting output in a user workpool session in the other. Usually, only one session in split-screen is active. To make the other session active, issue the `SWAP` command from the active session, or simply move the cursor to the inactive session and press ENTER.

If both sessions are edit sessions, both are active. This makes cross-session actions possible, for example, you can move or copy data from one session to the other. A common way to work with Natural is to run multiple sessions from your terminal with two sessions in split-screen mode.

### Multi-Session Operations

Working in multi-session mode means starting several parallel Natural sessions. You can control up to 20 active Natural sessions from your terminal. You can work in two parallel sessions displayed on your terminal simultaneously using the split-screen and `SWAP` features.

You can suspend one session and start another at any time using the `SUSPEND` and `SPLIT` session commands.

Typical examples of multi-session operations are copying data from one edit session to another, and editing a Natural program in one session and checking the resulting output in another.

The following figure illustrates a screen with Natural in multi-session mode:

       --------------------- NATURAL / NATURAL ISPF Main Menu ------------------------
       >------------------------ NATURAL VIEW - ENTRY PANEL --------------------------
       >>EDIT-PDS:FHI.JCL(ADAREP) ------------------------------------ Columns 001 072
        COMMAND===>                                                    SCROLL===> CSR
       ****** ****************************** top of data *****************************
       000001 //HKADAREP JOB  SAG,CLASS=X,MSGCLASS=X
       000002 //JOBLIB    DD   DSN=RZDBA.DB009.NEWLOAD,DISP=SHR
       000003 //          DD   DSN=RZDBA.DB009.LOAD,DISP=SHR
       000004 //REPORT    EXEC PGM=ADARUN
       000005 //*********************************************************************
       000006 //* DATABASE STATUS REPORT
       000007 //*********************************************************************
       000008 //DDASSOR1  DD   DSN=DB009.SYSF.ASSOR1,DISP=SHR
       000009 //DDDATAR1  DD   DSN=DB009.SYSF.DATAR1,DISP=SHR
       000010 //SYSUDUMP  DD   SYSOUT=X
       000011 //DDDRUCK   DD   SYSOUT=3                      -> ADAREP MESSAGES
       000012 //DDPRINT   DD   SYSOUT=*                      -> ADARUN MESSAGES
       000013 //DDCARD    DD   DISP=SHR,DSN=NPRTAD.SYSF.DB009.CONTROL(CADAREP)
       000014 //DDKARTE   DD   *                             <- ADAREP PARAMETERS
       000015 ADAREP      NOFDT,FILE=66,67,68,70,74,75,76,77,78,79,84,85,86
       000016 /*
       ****** **************************** bottom of data ****************************
       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

The screen shows two suspended sessions, one containing the Natural ISPF Main Menu, the other a session with the `VIEWS` facility; two sessions are displayed in split-screen mode, the top session contains a PDS object editing session, the bottom session contains a list of Natural objects.

Natural provides a special feature here: the `SEPARATE` session command separates the current screen from its session, thus creating two sessions out of one. This feature is especially useful in conjunction with the `SPLIT` command. For example, after selecting an object from a list with a line command, you can issue the command sequence

    SEPARATE;SPLIT

to display the object and the original list in separate sessions in split-screen mode.

#### Example:

If you enter the command `SEP;SPLIT 10` in the command line of the following screen, enter the line command `E` preceding the member `INPLISP` and press ENTER ...

       S*>>LIST-PDS:FHI.ESM.JCL(*) --------------------- Row 0 of 41 - Columns 010 076
        COMMAND===> sep;split 10                                       SCROLL===> CSR
          MEMBER            VV.MM  CREATED  MODIFIED TIME  SIZE   INIT   TID   ID
       ** ******************************** top of list *******************************
          ADACOP            01.12  19930430 19940929 13:38    170     44       HKA
          ADAREP            01.04+ 19941017 19980910 13:36     16     14       FHI
          CATDEV            01.26  19911202 19960604 19:16     32     19       HKA
          CMPLOAD           01.02  19900830 19931213 10:34      6      6       HKA
          DELENV            01.16  19910904 19970227 13:06     23     19       HKA
          ERRLODU           01.04  19911202 19970221 17:01     16     19       HKA
          FHITST            01.01  19970919 19970919 13:51      1      1       FHI
          FNATBACK          01.03  19971124 19971124 15:37     31     31       FHI
          IEBGENPQ          01.15  19950310 19971104 13:36     34     26       FHI
          IEBGNIMP          01.04  19950310 19970711 14:14     30     26       MZC
          IEBGNOWN          01.04  19970717 19971113 14:10     19     19       FHI
          IEBGNPQ2          01.25  19950310 19971104 15:06     63     26       FHI
          INPL              01.20  19910418 19970221 16:17     47     17       HKA
        e INPLISP           01.12  19971126 19971203 16:24     35    119       FHI
          INPLSCAN          01.12+ 19980212 19980603 10:50     16     17       FHI
          IUPD              01.01  19970221 19970221 16:37     18     18       HKA
          LDDMCT            01.06  19920601 19930125 13:02     23     23       HKA
       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

... the requested edit session with member `INPLISP` is displayed in a separate session in split-screen mode, up to Line 10:

       S*>>>EDIT-PDS:FHI.ESM.JCL(INPLISP) ---------------------------- Columns 001 072
        COMMAND===>                                                    SCROLL===> CSR
       ****** ****************************** top of data *****************************
       000001 //FHI  JOB FHI,MSGCLASS=X,CLASS=G,REGION=2500K
       000002 //INPLISP EXEC PGM=NATBAT22,
       000003 //   PARM=('DBID=9,FNR=40,FUSER=(,121),FSEC=(,16),IM=D,MT=0,MADIO=0',
       000004 //         'INTENS=1,MAXCL=0,AUTO=ON,FDIC=(,122)')
       000005 //STEPLIB DD  DSN=OPS.SYSF.PROD.LOAD,DISP=SHR
       000006 //*       DD  DSN=OPS.SYSF.V5.ADALOAD,DISP=SHR
       000007 //CMPRINT DD  SYSOUT=X
       --------------------- NATURAL / NATURAL ISPF Main Menu ------------------------
       OPTION  ===>
                                                                     User ID  VMU
                                                                     Time     14:34:09
        _ 1    NATURAL    - Development Functions                    Terminal DAEETCN8
        _ 2    NATURAL    - Development Environment Settings         Library  SYSISPHU
        _ 3    NATURAL    - Maintenance and Transfer Utilities       Node     148
        _ 4    NATURAL    - Debugging and Monitoring Utilities
        _ 5    NAT/NSPF   - Example Libraries

        _ 6    SAG        - SAG    Products
        _ 7    SYSTEM     - System Products
       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

#### Notes:

If the limit of 20 parallel sessions is reached and the user tries to open another session, the message: `No more sessions available` appears. If this message is received in a situation where fewer than 20 sessions are visible on the Activity Table (see description for the `ACTIVITY` command on the following page) consider the following:

1. Natural keeps a stack of sessions with 20 entries for each half (upper and lower) of the split screen.

2. For every menu level, one stack entry is created. This means that, if the user opens a session via the menu, the following entries are created:

   - Main Menu

   - Entry Panel

   - Object list

   - `EDIT` or `BROWSE` session

     Thus, for each "visible" session, four entries are required, so that the limit is reached with only five "visible" sessions.

3. The number of stack entries can be reduced by using direct commands.

The following commands are available to control multi-session mode of work:

Command | Explanation
--- | ---
`ACTIVITY` | Displays list of all your Natural sessions. The current session appears highlighted. You can select another session using the `P` line command, terminate a session by entering a hyphen (-) in the line command field, or `SWAP` sessions using the S line command. In the `Name` column of the list, you can enter a short name for the session for easy identification in a later `POP` command. Alternatively, you can enter the name of a PF key in the Name field. You can then press this PF key at any time to call the associated session (existing PF key definition is overridden).
`POP` | Calls the indicated session to display. The popped session appears in the section of your screen in which you entered the `POP` command. The required session is indicated: by placing the cursor on the session header line, or: by adding the session name as a command parameter (you can assign short names to sessions using the `ACTIVITY` command), or: by adding any string from the session header line as a parameter If an unqualified `POP` command is issued, a selection window with available sessions is opened.
`SEPARATE` | Separates the current screen from its session to split the session into two. Useful in conjunction with a subsequent `SPLIT` command to display two screens from the same original session.
`SPLIT` | Splits the screen to display two Natural sessions. If only one session is active, a new one is created. The screen is split at the line specified in the command parameters or at cursor position. The new session is started in the lower part of your screen. You can change the size of the screen portions devoted to each session by repeating the `SPLIT` command with an appropriate line number or the cursor position indicating the required split position.
`SUSPEND` | Suspends the current session and starts a new one: the suspended session is eliminated from display except the top line.
SWAP | When working in split-screen mode, makes the other session active: the cursor is automatically moved to the other session. When working in full-screen mode, calls another session to display in full-screen mode in wrap-around fashion.
`UNZOOM` | Reverses the previous `ZOOM` command.
`ZOOM` | Enlarges the current session to full screen. If any suspended sessions exist, their top lines are eliminated from display. In split-screen mode, the current session is enlarged to full screen. If you are in split-screen mode and have the top lines of suspended sessions displayed, two `ZOOM` commands are required (one to remove the header lines, one to enlarge the current session).

Additionally, the Editor provides some line commands that allow you to copy or move lines of data from one edit session to another. You can mark the line or lines you wish to move or copy in one edit session and mark the target line in another edit session.

The available line commands to mark the source lines are:

Command | Explanation
--- | ---
`C` | Copies this line
`CC` | Marks the first and last line of a block of data to be copied
`M` | Moves this line
`MM` | Marks the first and last line of a block of data to be moved

The available line commands to mark the target area are:

Command | Explanation
--- | ---
`A` | Inserts data after this line
`B` | Inserts data before

### Selecting a Function or Object

Natural makes it easy for you to select a function or object by providing an extensive system of prompt windows.

- To select a function, simply enter an asterisk (*) in the command line of the current screen. This opens a window with available functions. Select one by entering it in the input field of the window;

- To select a function for a particular object type, simply enter the object type in the command line of any system screen. This opens a window with all available functions for the object type.

  Note
  When requesting a list of functions for Natural objects, use the shortest possible abbreviation `N`. If you use `NAT` or `NATURAL`, it is interpreted as a logon request to Natural.

- To select an object for a particular function from the Main Menu, simply enter the function command in the command line of the Main Menu. This opens a window with available object types for the function.

See also the section Command Logic.

### ENTRY as Line Command

The `ENTRY` command displays the Entry Panel for the specified object type:

    ENTRY object-type

The `ENTRY` command is also available as line command from a list of objects. When issued as a line command, the Entry Panel of the object type is displayed, with the parameter fields filled with the values of the selected object. This is especially useful when working with objects that have long names (for example, datasets, Con-nect documents), and you wish to create a new object with a name similar to the selected object.

#### Example:

You have requested a list of all PDS members in the dataset `NATQA.NAT92.USERSRCE.D210903` using the command

    LIST DS NATQA.NAT92.USERSRCE.D210903

and wish to create the new member `NATPARA3`. Simply enter the `EN` line command for the member `NATPARA2` as follows:

    LIST-PDS:NATQA.NAT92.USERSRCE.D210903(*) -------- Row 0 of 67 - Columns 010 07
      COMMAND===>                                                    SCROLL===> PAG
        MEMBER            VV.MM  CREATED  MODIFIED TIME  SIZE   INIT   TID   ID
     ** ******************************** top of list ******************************
        NATPAALL          01.31  20091016 20200107 13:58     80     79       ALO
        NATPARAL          01.61  20110210 20210819 15:38    122     66       ALO
     EN NATPARA2          01.58  20110210 20200916 08:43    102     66       DANR
        NATPARBA          01.52  20110210 20210615 16:15    113     60       ALO
        NATPARBV          01.12  20110118 20210505 14:46     98     55       DANR
        NATPARB2          01.55  20110210 20200916 08:43     99     60       DANR
        NATPARCI          01.34  20091016 20210505 14:47    137     79       DANR
        NATPARCO          01.42  20100310 20210505 14:47    147     81       DANR
        NATPARCZ          01.36  20100310 20200107 14:01    130     81       ALO
        NATPARC4          01.09  20110210 20190626 12:58     77     77       GRE
        NATPARDV          01.01  19950825 20130306 14:50     71     73       GRE
        NATPAREX          01.10  20161026 20190626 13:01     31    269       GRE
        NATPARIM          01.45  20110210 20210505 14:48    143     78       DANR
        NATPARIO          01.13  20110210 20181219 13:19     78     78       GRE
        NATPARIX          01.10  20110210 20181219 13:19     81     80       GRE
        NATPAROO          01.43  20100310 20210512 10:37    131     81       DANR
        NATPARSF          01.10  20110210 20181219 13:19     81     80       GRE
        NATPARTS          01.26  20110210 20210505 14:48    135     76       DANR

       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

The PDS Objects - Entry Panel is displayed with the parameter fields filled:

       ------------------------- PDS OBJECTS - ENTRY PANEL ---------------------------
     COMMAND ===>

        Data Set Name ===> NATQA.NAT92.USERSRCE.D210903
        Member        ===> NATPARA2
        Volume        ===> FSM019                  ( If not catalogued     )
        Password      ===>                         ( If password protected )
        Scan for      ===>
        Edit macro    ===>
        Node          ===> 148

      Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
            Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

All you need to do is change the member name to `NATPARA3` and press ENTER to start the required edit session with the new member.

### Cursor-Sensitive String Selection - :C Directive

#### In the Editor and any other Natural Session

Natural provides a feature which makes input of commands in the command line more comfortable.

In any session (`LIST`, `EDIT` or `BROWSE` mode), command input can consist of typing in command keywords plus any word selected from the data displayed. The word is selected by typing `:C` in the command line and placing the cursor on the first character of the required word. When you press ENTER, the `:C` notation is substituted by the selected string, and the completed command is executed.

##### Example of :C Notation:

    >>EDIT-PDS:MBE.SYSF.SOURCE(NOJC02)------------------------------ columns 001 072
     COMMAND ===> edit :C
    00010 //MOVE A TO B
    000020 //INCLUDE MYPROG

With the command

    EDIT :C

in the command line, move the cursor to the string `MYPROG` and press ENTER. The command executed is

    EDIT MYPROG

Note
You might find it useful to assign the command `SUSPEND;E :C` to an available PF key.

#### In the Online Help System

When you are scrolling help texts in the online help system, you can enter `HELP :C` in the command line, place the cursor on a word and press ENTER to see the help text on that word, if available. Assigning the `HELP :C` directive to a PF key makes this quick cross reference to other help texts even more comfortable.

### Automatic Transfer of Commands

To make using Natural even easier, commands are accepted in many situations, although they are syntactically not quite correct. Such commands are transferred to another object depending on the context, thus saving the user additional entries or steps. Two examples follow:

#### From PDS to Datasets

You can access partitioned and sequential data sets by using two Natural facilities, the PDS objects facility and the Datasets facility.

If you wish to maintain PDS members using function command syntax from outside the PDS objects facility, you must address Object Type `P`. If you wish to access datasets with function command syntax, you must address Object Type `D`.

However, if you are in the PDS facility, you can use a command pertaining to datasets. The command is transferred automatically (and invisibly to you) to the Datasets facility and executed there. The command is:

    COMPRESS

This feature provides added convenience when, for example, you wish to save a modified PDS member and a message tells you that the dataset is full.

#### From Active Jobs to Job Information

If you select a job from a list of active jobs with the `B` line command (`BROWSE`), you are automatically transferred to the job information facility.

### Command Redisplay Feature

#### In any Natural Screen

With the `LAST` command, you can retrieve the last 10 (ten) commands you entered. A window opens with a list of the commands. You can select any command for reexecution by placing the cursor on it and pressing ENTER. You can modify the command by overtyping it before execution. This also applies to Editor command strings.

If a command is executed again, it is always put on top of the last command buffer. This keeps the commands used most in the buffer. Additionally, you can also delete commands from the last buffer. Commands not used again can be deleted; this avoids automatic deletion of commands likely to be reused. You can delete the command from the buffer by setting the entire line to blanks and pressing ENTER.

Only commands consisting of two words or more and entered via the keyboard are stored and appear in the window: commands executed by PF key, magic character or by selection from a prompt window are not stored.

#### In the Editor

Additionally, any Editor command entered in the command line of an Editor screen (`LIST`, `BROWSE`, `EDIT`) remains in display after execution if preceded by an ampersand (&). This applies to Editor commands only.

Example:

You may find this feature useful, for example, in combination with the commands `RFIND` (to scan for all occurrences of a search string) or `XSWAP` (to exchange displayed lines and excluded lines).

### Editor Sessions

The Software AG Editor is integrated in Natural. Certain commands issued from a Natural screen automatically start an Editor session: `EDIT`, `BROWSE`, `LIST`. This means that lists of objects, and objects displayed in edit or browse mode constitute Editor sessions and you can use any appropriate Editor command.

In `LIST` or `BROWSE` mode, you can therefore use any Editor command that does not change the data. This includes not only scroll commands (`UP`, `DOWN`, `BOTTOM`, `TOP`, `LEFT`, `RIGHT`, etc.), but also other commands such as `FIND`, `CREATE`, `HEX`, etc., corresponding Editor line commands, as well as the C/CC line commands.

This means, for example, that you can copy lines from a list into another member in a cross-session copy operation, or store a list in a member as data that can be edited.

#### Example:

You wish to store a list of members from Natural library `MYLIB` as a PDS member. From the Main Menu, issue the command:

    L N MYLIB(*)

This displays the required list on your screen. In the command line of the list, enter the command:

    CREATE P USER.LIB(LIBLIST)

and mark the first and last lines of the block to be stored with a `CC` line command as follows:

       LIST-NAT:MYLIB(*) -------------------------------- Row 0 of 7 - Columns 010 076
        COMMAND===> create p user.lib(liblist)                         SCROLL===> CSR
          MEMBER            PGMTYPE     SM S/C VERSION   USERID   DATE     TIME  VV.MM
       ** ******************************** top of list *******************************
          ISPNHVKN          Subprogram  S  S/C 3.1 0006  UKSJU    20030319 16:02
       CC ISPNIN-N          Subroutine  S  S/C 3.1 0006  JWO      20020904 16:56
          ISPNIN-P          Program     S  S/C 8.2 0001  BLI      20110112 15:00 01.09
          ISPNIN-1          Map         R  S/C 8.2 0001  BLI      20101208 16:59
          ISPNLDRP          Program     S  S/C 4.1 0004  FHI      20060320 10:04
          ISPNLS-L          Local          S/C 8.2 0001  BLI      20101210 18:48
       CC ISPNLS-P          Program     S  S/C 8.2 0001  BLI      20110131 18:27 01.25
       ** ****************************** bottom of list ******************************

      Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
            Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

When you press ENTER, the marked list is created as member `LIBLIST` in PDS library `USER.LIB` (a message confirms successful creation).

### Editor Session with No Prefix

You can work with an Editor session in `EDIT` or `BROWSE` mode without the prefix area (line numbers) displayed. The data area is then increased by 7 columns. This feature is controlled by the `PREFIX` session command.

The command format is:

    PREFIX  [ON]
            [OFF]

The default value is `ON`. When the prefix area is `OFF`, you can issue line commands by typing them in the data area preceded by the escape character.

### Online Help Facility

Natural includes a comprehensive online help system which provides information about the Natural facilities and helps you select the appropriate function, command or item from any system screen.

The online help system consists of active help and passive help:

- Active Help

  Lists selectable options in windows and is invoked by entering an asterisk (*) in input fields or instead of object parameters in function command syntax (see also the subsection Selection Windows and Wildcards in section Command Logic);

- Passive Help

  Displays general information on the selected item and is invoked

  - at screen level by entering the `HELP` command in the `COMMAND==>` or `OPTION==>` field and pressing ENTER;

  - at field level by entering a question mark (?) in the appropriate field and pressing ENTER;

  - at message level by entering the `HELP` command followed by message number in the `COMMAND==>` or `OPTION==>` field.

The following subsections describe how to use the active and passive help systems.

#### Active Help

Active help always offers you a selection list of Natural commands, functions or objects. If you select an item from the list, Natural prompts for missing parameters/options for the selected function until the command can be executed.

Active help is usually invoked by entering an asterisk (*) in the command line and pressing ENTER. The type of information displayed depends on the type of screen where you invoke active help.

The following subsections describe four examples of active help (in a Menu, Entry Panel, `LIST` and Editor session) in more detail.

> Natural Menu

>   If you invoke active help in a menu, it lists all available function commands at your site. If you select a function from the list, you are prompted for the object (e.g. Natural or PDS) and then for missing parameters.

>   Below is an example of an active help screen invoked from the Natural ISPF Main Menu:

>          --------------------- NATURAL / NATURAL ISPF Main Menu ------------------------
>          OPTION  ===> +---------------------------------------------------+
>                       ! ENTER FUNCTION:                                   ! ID  VMU
>                       !   1 L  LIST               17 ET EXTENTS           !     14:11:05
>           _ 1    NATU !   2 B  BROWSE             18 FL FOLLOW            ! nal DAEETCK7
>           _ 2    NATU !   3 E  EDIT               19 ST STATUS            ! ry  SYSISPHU
>           _ 3    NATU !   4 D  DELETE             20 CC COND.CODES        !     148
>           _ 4    NATU !   5 R  RENAME             21 RL RELEASE           !
>           _ 5    NAT/ !   6 SB SUBMIT             22 HL HOLD              !
>                       !   7 PL PLAY               23 DI DIFFERENCE        !
>           _ 6    SAG  !   8 PR PRINT              24 PG PURGE             !
>           _ 7    SYST !   9 CP COPY               25 CH CHANGE            !
>                       !  10 CM COMPRESS           26 DF DEFINITION        !
>           _ 8    NSPF !  11 ZP ZAPS               27 RU RUN               !
>                       !  12 XT EXTERNS            28 XE EXECUTE           !
>           _ 9    NSPF !  13 A  ALLOCATE           29 EX EXPORT            !
>                       !  14 CT CATALOG            30 DS DESCRIPTION       !
>           _ HELP HELP !  15 U  UNCATALOG          and others...           !
>           _ NHLP HELP !  16 I  INFORMATION        Select ==> __           !
>           _ END  EXIT +---------------------------------------------------+

>          Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
>                Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

>   To display an explanation of a listed function, enter the function's number or code in the `Select ==>` field and press PF1. This invokes the passive help system.

> Natural Entry Panel

>   If you invoke active help from an Entry Panel, a list of all available function commands for the selected object is displayed. If you select a function from the list, it checks whether the fields in the Entry Panel already contain a sufficient object identification; if not, you are prompted for the missing parameters.

>   Below is an example of an active help screen invoked from the Natural View - Entry Panel:

>          ------------------------ NATURAL VIEW - ENTRY PANEL ---------------------------
>          COMMAND === +--------------------+
>                      ! ENTER FUNCTION:    !
>                      !   1 L  LIST        !
>             View Nam !   2 B  BROWSE      !
>             Dbid     !   3 CP COPY        !                       (For selection list)
>             Fnr      !   4 DF DEFINITION  !                       (For selection list)
>             Record F !   5 DS DESCRIPTION !
>             Start va !   6 DW DOWNLOAD    !
>             End valu !   7 UP UPLOAD      !
>             Max Reco !  Select ==> __     !
>             Password +--------------------+

>   To display an explanation of a listed function, enter the function's number or code in the `Select ==>` field and press PF1. This invokes the passive help system.

> Line Command Help in LIST Session

>   Invoking active help in a list usually displays the same list as invoked from an Entry Panel.

> Natural Editor screen

>   If you invoke active help from an `EDIT`/`LIST`/`BROWSE` screen, all available local commands for the selected object and function are displayed. If you select a function from the list, the function is executed.

>   Use PF7 / PF8 for scrolling if more than 10 commands are available, or PF3 to abort. If you press ENTER without any selection, a list of all function commands is displayed.

>   Do not forget, if you need information about Editor commands just enter: `HELP EDITOR`.

>   Below is an example of an active help screen invoked from an edit session for a Natural program:

>          EDIT-NAT:NSPFEXAM(API-002P)-Program->Struct-Free-45K ---------- Columns 001 072
>           COMMAND===> *                                                  SCROLL===> CSR
>          ****** ****************************** top of data *****************************
>          000010 DE +-------------Local command help-------------+
>          000020 LO !                                            !
>          000030 *  !  1  SM                6  TYPE              !
>          000040 *  !  2  STOW              7  STRUCT            !
>          000050 *  !  3  CHECK             8  OUTPUT            !
>          000060 1  !  4  CAT               9  IMPORT            !
>          000070 1  !  5  RUN               10 PLAY              !
>          000080 1  !                          more...           !
>          000090 *  !  Select  __ or press enter for global help !
>          000100 *  +--------------------------------------------+
>          000110 *
>          000120 1 #ERR-NUMBER (N4)
>          000130 1 #ERR-TEXT   (A75)
>          000140 1 #ERR-PARM   (A75)
>          000150 *
>          000160 * local data
>          000170 *
>          000180 1 #LGT       (N2)
>          000190 1 #IN-DSN    (A44)
>          Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
>                Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

>   To display an explanation of a listed function, enter the function's number in the Select field and press PF1. This invokes the passive help system.

#### Passive Help

Passive help texts are available on three levels:

- Screen level;

- Message level;

- Field level.

The following subsections describe the three levels of passive help in more detail.

> Screen-level Help

>   The hierarchy of the help screens reflects the hierarchy of Natural system screens. This means that you can invoke the online help facility from any system screen and you immediately see the help text defined for that screen. Invoke a screen help by issuing the `HELP` command (usually assigned to PF1) from any system screen, or by typing a question mark (?) in the command line and pressing ENTER. This displays a help text with general information on the screen from which you invoked the online help.

>   The help text displayed can be one of two types:

>   - User-defined help;

>   - Screen-dependent help text from the online help facility.

>   The user-defined help can be linked to a menu customized to your installation and is maintained in a separate library by the system administrator (see also the Natural ISPF Administration Guide). If you issue the `HELP` command from any menu, the user help library is searched before the system help.

>   You can enter the online help facility at the top end of the hierarchy by issuing the `HELP` command (usually assigned to PF1) from the Natural ISPF Main Menu. This displays the main Help Menu on your screen with a list of selectable items:

>          Z*HELP------------------------Table-of-contents------------------>>> continued
>          COMMAND ==>                                                          MAIN

>                                      NATURAL-ISPF HELP
>               Please select a topic by entering a numerical code

>          PART I: Working with NATURAL ISPF

>                1  Help system
>                2  Command Logic
>                3  NATURAL ISPF Commands
>                4  Useful Features

>          PART II: Common Functions

>                5  User Workpool
>                6  Recovery Files
>                7  Profile Maintenance
>                8  NATURAL ISPF Editor

>          PART III: NATURAL

>         Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
>               Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

>   The Help Menu can consist of several screen pages. Use the `UP` and `DOWN` commands (usually assigned to PF7 and PF8) to scroll the menu.

>   To select an item, enter its number in the command line at the top of the menu and press ENTER. This displays a help text for the selected item.

>   The `HELP` command is also available with a number of parameters to allow you to call help texts on any Natural item from any system screen.

>       HELP  [INDEX]
>             [object]
>             [:C]

>   where:

>   Parameter | Meaning
>   --- | ---
>   `INDEX` | Lists all objects for which there is a help text. You can specify any object in a `HELP` command to display the related help text.
>   `object` | The object for which a help text is required. This can be any object listed by the `HELP INDEX` command. Use the asterisk wildcard (*) to generate selection lists of objects with the same prefix (see examples below).
>   `:C` | Is substituted by the string marked by the cursor (see the subsection Cursor-Sensitive String Selection). If you use the `:C` directive, you need not enter the `HELP` command keyword.

>   Examples:

>   Command | Meaning
>   --- | ---
>   `HELP LIST` | Displays the help text for the command `LIST`.
>   `HELP L*` | Displays a selection list of all items and commands starting with `L` for which there is a help text. You can select any item from the list to display the associated help text.
>   `HELP FEATURES` | Displays help text for special Natural features.
>   `HELP EXAMPLES` | Displays an overview of example programs, macros and command scripts supplied in the Natural Examples Library.
>   `HELP :C` | With cursor on string "edit", executes the command `HELP EDIT`.

>   A help text may consist of more than one page. If this is the case, you are notified by the message `Continued...`. Use PF7 and PF8 to browse though the help pages. A special local command is also provided here. The command `UP L` or `BACK` scrolls up to the next higher level in the screen hierarchy. Alternatively, you can enter `L` in the command line and press PF7.

>   Some help screens provide direct access to help texts on a related item or on another level in the help screen hierarchy. You can enter the selected item in the command field at the top of the help screen and press ENTER to see the associated help text.

>   Alternatively, you can enter `HELP :C` in the command line, place the cursor on a word in the help text and press ENTER to display the help text on that word. Assigning the `HELP :C` directive to a PF key makes this cross reference even more comfortable (see the subsection PF Key Assignments in section Command Logic).

>   To print a help text as displayed on the screen, enter the `PRINT` command and press ENTER.

>   Note
>   Words which appear in the help text in reverse video (on color terminals, yellow) have separate help texts defined for them. Place the cursor on the word and press the help key to display the corresponding help text.

>   To leave the online help facility, issue the `END` command (usually assigned to PF3).

> Message-level Help

>   The online help facility also allows you to display information on error messages. This is done using the following command from any Natural screen:

>   Command | Meaning
>   --- | ---
>   `HELP nnnn` | Displays a help text for error message Number nnnn. This can be any existing error number of Natural, or any other related Software AG product installed at your site.

>   If a Natural or Natural error occurs, a special feature is provided that enables you to issue a `HELP` command without parameters. This displays a help text on the last error.

> Field-level Help

>   You invoke a field help from a system screen by typing a question mark (?) in the selected input field and pressing ENTER. This opens a window with an explanation of the field and how to use it. Press ENTER to close the window.

### Online Technical and Site-Specific Information

Natural provides some technical information online relevant to the system administrator for system identification and debugging purposes, as well as a facility with which the system administrator can provide site-specific information.

The `TECH` command opens a window with information that includes the following information:

- Current versions of Natural ISPF, the SAG Editor and Entire System Server

- Values of the `ASIZE` and `SSIZE` parameters

- Library, current date and time, terminal ID, TP monitor and operating systems

The `TECH ALL` command shows, in addition to above described `TECH` information, details about installed hotfixes and corrections.

The `UINFO` command displays site-specific information maintained by the system administrator. This information may consist of several screens. Navigation among Information screens is done by PF key, scroll commands or topic selection, as directed in the screens.

### Confirmation Windows

When you wish to perform certain functions on a Natural object using function commands (e.g. `DELETE`, `COMPRESS`), a window is opened in which Natural asks you to confirm the function by entering the object name or `Y`. You can back out the request simply by leaving the input field in the window blank and pressing PF3.

You can suppress the confirmation feature with the command

    CONFIRM  OFF

for example when deleting objects from a list using multiple `D` line commands in a single input operation. The message `CONFIRM OFF` is displayed in the message line. The function is then performed without confirmation. The confirmation feature is automatically reactivated when you invoke another system screen, or you can issue one of the following commands:

    CONFIRM LONG
    CONFIRM SHORT

where `LONG` specifies confirmation by name input and `SHORT` specifies confirmation by entering `Y` or `N` in the confirmation window.

The default is `CONFIRM SHORT` and can be modified in your user profile using the `PROFILE` option on the Natural Main Menu (see the subsection User Defaults in the section Profile Maintenance). See also the description of the `CONFIRM` session command in the section Command Reference.

### Using the Trace Function

Natural provides a feature that allows you to trace Natural activity while CPU time is being consumed. After a command is issued and a predefined time interval has elapsed before the next screen output, a window opens informing you of Natural activity. The message is updated after each interval of the specified length until the function is completed.

The interval after which the trace window appears is specified in your user profile. You can modify this interval using the `TRACE` command.

Examples of the `TRACE` command:

Command | Meaning
--- | ---
`TRACE 10` | If a function takes more than 10 seconds to complete, the trace window appears after 10 seconds of elapsed time. The window is updated every 10 seconds.
`TRACE 00` | Trace function is disabled.
`TRACE OFF` | Trace function is disabled.

For example, if the trace interval is set at 3 (`TRACE 3` command), and you issue a `LIST` command with the `SCAN` option in the PDS facility (that is, only those members are listed which contain the string specified with the `SCAN` keyword), a message similar to the following appears in a window if after 3 seconds the function is not completed:

    PROCESSING   4 MEMBERS

The message is updated every 3 seconds until the function is complete and the requested list is displayed.

### Break in Processing

The `BREAK` function allows you to abort Natural activity if it takes too long or if it has been started by mistake.

In addition to the `TRACE` value (see above), you can define a `BREAK` value in your user profile. This causes Natural to prompt you whether to abort or continue with the current function. This feature is available with the `LIST` function.

For example, if you set the `BREAK` value at `3` and you issue a `LIST` command that reads a large number of data, you are prompted to interrupt processing if after 3 trace windows the function has not completed:

    PROCESSING   104 MEMBERS
    BREAK PROCESS(Y/N) _

You can abort the function by entering `Y` in the input field. `N` continues the function.

The `BREAK` value can be modified either directly in your user profile or using the `BREAK` session command:

Command | Meaning
--- | ---
`BREAK 2` | You are prompted to abort the function every 2 trace windows.
`BREAK 00` | Break function is disabled.
`BREAK OFF` | Break function is disabled.

### Automatic Screen Refresh

Refreshes the display of the current screen.

The command format is:

    REFRESH nn

The screen is refreshed automatically every nn seconds until the user presses the attention interrupt key, to return to normal command input mode. This is especially useful if a user wants to monitor active jobs or browse the console/log without pressing ENTER.

This function is not supported in all TP environments (i.e. IMS-TM).

#### Example:

For example, if you enter the command `REFRESH 2` in the command line of the following console screen and press ENTER ...

        BROWSE-CON:/NODE=148/TYPE=ALL --------------------------------- Columns 001 076
        COMMAND===> REFRESH 2                                         SCROLL===> CSR
          JOB03635  -KHKLOAD  ENDED.  NAME-                     TOTAL TCB CPU TIME=
           TOTAL ELAPSED TIME=   1.2
          JOB03635  .HASP395 KHKLOAD  ENDED
          JOB03640  .HASP373 KHKLOAD  STARTED - INIT  1 - CLASS G - SYS DAEF
          JOB03640  IEF403I KHKLOAD - STARTED - TIME=16.34.46
          STC03689  +ESY007I INACTIVE USER          ESYID 0335 HAS BEEN PURGED
          STC03689  +ESY007I INACTIVE USER          ESYID 0336 HAS BEEN PURGED
          STC03689  +ESY007I INACTIVE USER          ESYID 0337 HAS BEEN PURGED
          STC02112  ACF01200 INVALID PASSWORD/AUTHORITY FOR ID HGS FROM
          STC02112  ACF01012 PASSWORD NOT MATCHED
          STC02346  NETT004I: 06 - DIS-CONN       Admin REQ From Node PCBTO    Receive
          STC02346  NETP107W: Trecv    API Call Failed, R15=00000004 R0=00000008 For P
            157.189.161.138
          STC02346  NETP102W: Error Code=TERELESE (Connection Release Received   )
          STC02346  NETP001W: Error During Receive RC=(08) Link=LNKPCBTO
          STC02346  NET0107I DAEFNODE: Link LNKPCBTO disconn. from node PCBTO
          STC02085  ESY007I INACTIVE USER SAGEJE   ESYID 0719 HAS BEEN PURGED
          JOB03642  .HASP100 ECKLOD   ON INTRDR                          FROM STC02077
           DAEFCO
       ** ****************************** bottom of list ******************************
       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

... the screen is refreshed every 2 seconds:

        BROWSE-CON:/NODE=148/TYPE=ALL --------------------------------- Columns 001 076
        COMMAND===>                                                    SCROLL===> CSR
          JOB03644  -KAS      ADAFRM               00   1788   3682    .00    .00
           10210   4     0     0     0     0
          JOB03642  -ECKLOD   LD       ADARUN      00    311    776    .00    .00
           3315   1     0     0     0     2
          JOB03642  IEF404I ECKLOD - ENDED - TIME=16.36.17
          JOB03642  -ECKLOD   ENDED.  NAME-                     TOTAL TCB CPU TIME=
           TOTAL ELAPSED TIME=    .3
          JOB03642  .HASP395 ECKLOD   ENDED
           .HASP309    INIT  2 INACTIVE ******** C=G
          STC03754  IEC130I SYSOUT   DD STATEMENT MISSING
          STC03754  +WER045C NSNSERV ,NSNSERV ,         - END SORT PH
          STC03754  +WER177I NSNSERV ,NSNSERV ,        -TURNAROUND SORT PERFORMED
          STC03754  +WER055I NSNSERV ,NSNSERV ,        -INSERT         6, DELETE
          STC03754  +WER246I NSNSERV ,NSNSERV ,        -FILESIZE 42 BYTES
          STC03754  +WER054I NSNSERV ,NSNSERV ,        -RCD IN         0, OUT
          STC03754  +WER169I NSNSERV ,NSNSERV ,        -TPF LEVEL 3B
          STC03754  +WER052I NSNSERV ,NSNSERV ,        -END SYNCSORT - NSNSERV,NSNSERV
           DIAG=CC00,8C08,227C,E49D,CD7E,8C09,226C
          STC03479  TMN001C DAEFCO uses 61.26% CPU --> from TMON
       ** ****************************** bottom of list ******************************
       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

## Functional Features

The following topics are covered below:

- Versioning

- Recovery

- Copying Objects

- Printing Objects

- Natural Interface to External Environments

- Message Switching

- Using the Calculator

- Using the Macro Facility

- Executing Command Scripts

### Versioning

Natural can keep previous versions of the following object types after they have been edited and saved (`SAVE` command) or stowed (`STOW` command, for Natural programs):

- Natural members (but not for maps and data areas)

- PDS members

- CA Librarian members

Note
This section describes versioning of Natural and z/OS objects only. Versioning for CA Librarian members is described in the subsection Previous Versions in section CA Librarian Members.

For a previous version of an object to be available, versioning must be enabled, or one of the following conditions must be true:

- The member must already have previous versions, or

- The library is specified in the versioned library list maintained by the system administrator.

Versioning is enabled at the user level in the user defaults using the `PROFILE` option on the Natural Main Menu, and/or can be activated or deactivated for the session using the `VERSIONS ON/OFF` command.

How many versions of a member are to be stored is specified by the system administrator in the NSPF Parameters by selecting the `CONFIG` option from the Administrator Menu and the NSPF option from the Configuration Menu. This value can be overridden for a member from the Information screen for the member. The system administrator also specifies the database number and file number where versions are kept.

Notes:

1. If the maximum number of versions is reached, a subsequent `SAVE` or `STOW` command automatically deletes the oldest version not on `HOLD` (see the `HOLD` command below);
2. If you rename a member, all versions are renamed;
3. If you replace a member using the `COPY` command, all previous versions are deleted.
4. The command `VERSIONS OFF` will affect only members that have not yet been versioned. If `VERSIONS OFF` is issued, a member with existing versions will be still versioned unless all versions of the member are deleted.

#### Retrieving Previous Versions

Previous versions are separate object types that can be addressed using the following object type notations in function commands:

Notation | Meaning
--- | ---
`NV` | Natural object versions
`PV` | PDS object versions
`MV` | all object versions

You can retrieve previous versions of a member in any of the following ways:

1. If you have administrator status, using the `VERSIONS` option on the Administrator Menu.

2. From the object's Entry Panel, issue the `LIST` command with the library and member names specified. This generates a list of versions for the member.

   Note
   You must explicitly enter the `LIST` command; if you leave the command line blank, the command defaults to `EDIT`, and an edit session with the last version is started.

3. From any system screen using the `LIST` or `BROWSE` function command in any of the following formats:

       LIST N/P/LIB/ LIBRARY(MEMBER)

   for a list of versions for the member of the specified object type, or:

       LIST NV/PV/LV/LMV/VV/MV LIBRARY(MEMBER)

   for a list of versions for the member of the specified object type, or:

       LIST MV

   for a list of all members of all object types for which there are previous versions, or:

       BROWSE NV/PV/LV/LMV/VV  LIBRARY(MEMBER)

   to display a version of the member. A window opens with the object parameters of the last version. You can modify any parameter, for example the date/time parameter to see an earlier version.

Note
Versioning of CA Librarian members is described in the subsection Previous Versions in section CA Librarian Members.

##### Example 1: Listing previous versions of a PDS member

The following screen lists previous versions of a PDS member obtained using the command:

    LIST PV FHI.JCL(COPYNSPF)

       LIST-PV:FHI.JCL(COPYNSPF) ------------------------ Row 0 of 2 - Columns 008 076
        COMMAND===>                                                    SCROLL===> CSR
           VV.MM          MODIFIED TIME     SIZE   ID       CHANGE REASON
       ** ******************************** top of list *******************************
           01.07          19980603 10:07        27 FHI
           01.06          19980603 09:55        27 FHI
       ** ****************************** bottom of list ******************************

Meaning of column headings:

Column | Meaning
--- | ---
`VV.MM` | Version and modification level. If a version is in `HOLD` status, this field is highlighted.
`MODIFIED` | Date of modification
`TIME` | Time of modification.
`SIZE` | Number of lines.
`ID` | User ID of user who saved this version.
`CHANGE REASON` | Brief indication for reason of the modification from one version to the next (see the subsection Reason for Change).

You can select any version with the `B` (`BROWSE`), `CH` (`CHANGE`), `D` (`DELETE`), `DI` (`DIFFERENCE`), or `HL` (`HOLD`) line command. These functions are described in a separate subsection below.

##### Example 2: Listing previous versions of a Natural member

The following screen illustrates a list of previous versions of a Natural member obtained using the command:

    LIST NV MYLIB(MYPROG)

       LIST-NV:MYLIB(MYPROG) ---------------------------- Row 0 of 3 - Columns 011 076
        COMMAND===>                                                    SCROLL===> CSR
          NUM VV.MM          MODIFIED TIME     ID       CHANGE REASON
       ** ******************************** top of list *******************************
            0 01.02          19980722 15:07:30 FHI
           -1 01.01          19980722 15:07:05 FHI
           -2 01.00          19941124 18:58:59 MZC
       ** ****************************** bottom of list ******************************

Meaning of column headings:

Column | Meaning
--- | ---
`NUM` | Version number: zero (0) indicates the most recent version.
`VV.MM` | Version and modification level. If a version is in `HOLD` status, this field is highlighted.
`MODIFIED` | Date of modification.
`TIME` | Time of modification.
`ID` | User ID of user who saved this version.
`CHANGE REASON` | Brief indication for reason of the modification from one version to the next (see the subsection Reason for Change).

You can select any version with the `B` (`BROWSE`), `CH` (`CHANGE`), `D` (`DELETE`), `DI` (`DIFFERENCE`), or `HL` (`HOLD`) line command. These functions are described in a separate subsection below.

#### Available Functions for Previous Versions

##### Relevant for object types NV, PV, VV and MV

The functions available for previous versions are `BROWSE`, `CHANGE`, `DELETE`, `DIFFERENCE` and `HOLD`. All commands can be executed as line commands from lists of previous versions or as function commands with appropriate parameters from any Natural screen.

The following table provides an overview of these functions. More detailed information and examples follow.

Function | Line Command | Meaning
--- | --- | ---
`BROWSE` | `B` | Display specified version (no modification possible).
`CHANGE` | `CH` | Add/modify change reason of a specified version.
`DELETE` | `D` | Delete specified version.
`DIFFERENCE` | `DI` | Display difference between current version and specified version.
`HOLD` | `HL` | Hold current version, thus preventing it from being automatically deleted.

> BROWSE

>   You can select a previous version from a list of versions with the `B` line command, or you can issue the `BROWSE` function command from any system screen.

>   #### Example:

>   For example, the command:

>       BROWSE PV MY.OWN.LIB(MEM)

>   requests a display of a previous version of PDS member `MEM` in the library `MY.OWN.LIB`. The command opens a prompt window in which you can specify which version you require by date and/or time:

>         +------------------------------------------------+
>         ! BROWSE-PDSVER:                                 !
>         ! Dataset Name  ===> MY.OWN.LIB                  !
>         ! Member        ===> MEM                         !
>         ! Date          ===> 93/08/02-11:30              !
>         ! Volume        ===>                             !
>         ! Password      ===>                             !
>         ! Node          ===> 148                         !
>         +------------------------------------------------+

>   The current data and time is the default, meaning the current (or latest) version is selected. If you do specify the exact date or time, the version closest to the specification is selected:

>         BROWSE-PV:MY.OWN.LIB(MEM)-V01.03-93/07/29-11:14 --------------- Columns 001 072
>          COMMAND===>                                                    SCROLL===> CSR
>         ****** ****************************** top of data *****************************
>         000001 This is the third version of a PDS member.
>         000002 This is the third version of a PDS member.
>         000003 This is the third version of a PDS member.
>         ****** **************************** bottom of data*****************************

>   Note that the header line gives an indication as to the version number and modification level, as well as the date and time the version was created.

> CHANGE

>   The `CHANGE` command is available for any previous version of a member. It is available as the line command `CH` only. The `CHANGE` command allows you to add/modify the `CHANGE REASON` of a version. A window opens in which you can modify/enter the change reason:

>         LIST-NV:MYLIB(MYPROG) ---------------------------- Row 0 of 3 - Columns 011 076
>          COMMAND===>                                                    SCROLL===> CSR
>            NUM +---------------------------------------------------------------------+
>         ** *** !                                                                     !
>              0 !  Enter reason for change: ________________________________________  !
>         ch  -1 !                                                                     !
>             -2 +---------------------------------------------------------------------+
>         ** ****************************** bottom of list ******************************

> DELETE

>   You can delete any version of an object by selecting it with the `D` line command from a list of previous versions, or by issuing the `DELETE` function command with the appropriate object type and object parameters.

>   #### Example:

>   For example, the command:

>       DELETE PV MY.OWN.LIB(MEM)

>   Opens a prompt window similar to the one described for `BROWSE` above, and you can select the version to be deleted by specifying the version date and/or time.

>   If you delete the current version of an object, the previous version becomes the current version. When the object is listed (for example, `LIST PDS`), the modification date and time are refreshed to the date and time of the previous version. In lists of Natural members (`LIST NAT`), however, the `DATE` and `TIME` fields of the "new" current version reflect the date and time of the delete operation.

>   #### A Note on Storage:

>   Storage occupied by previous versions is only freed after a `DELETE` operation if the oldest or most recent versions are deleted.

> DIFFERENCE

>   The `DIFFERENCE` function is available for any previous version of a versioned object. It displays the current version together with any changes made during the period between the selected version and current version. Changes are indicated by highlighting and a corresponding remark in the prefix area.

>   #### Example:

>   The following figure illustrates the result of the `DIFFERENCE` command on a previous version of Natural member `MYPROG` in library `MBE`:

>         DIFFERENCE-NV:MBE(MYPROG)-Ver<-2>-93/08/02-16:31:08 ----------- Columns 011 076
>          COMMAND===>                                                    SCROLL===> CSR
>         ** ******************************** top of list *******************************
>               000010 * NSPF - GET MODEL VARIABLES ( CALLNAT TO ISP--MVN )
>             Old>0010 * NSPF - GET MODEL VARUABLES ( CALLNAT TO ISP--RVN )
>               000020 DEFINE DATA
>               000030 GLOBAL USING ISP---GL
>             Old>0030 GLOBAL USING ISP----G
>               000040 LOCAL
>               000050 1 #REQUEST(A8)
>               000060 1 #RETURN(A8)
>             New>0070 1 #NEWFIELD(A8)
>               000080 END-DEFINE
>               000090 MOVE ##NAT-REQUEST TO #REQUEST
>               000100 CALLNAT 'ISP--MVN' #REQUEST #RETURN ##ISPF-ERC ##ISPF-ERT ##SES-DA
>             Old>0100 CALLNAT 'ISP--RVN' #REQUEST #RETURN ##ISPF-ERC ##ISPF-ERT ##SES-DA
>               000110   ##ED-SESNUM(0)
>               000120 MOVE #RETURN TO ##TEMP-A20
>             Del>---- END-SUBROUTINE
>               000130 END
>         ** ****************************** bottom of list******************************

>         Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
>               Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right :s

>   - The lines with no remark in the prefix area are those of the current version.

>   - The highlighted lines with `Old` in the prefix area indicate the lines which have been changed. The modified line in the current version is directly above the `Old` line.

>   - The highlighted lines with `Del` in the prefix area indicate the lines that have been deleted and no longer exist in the current version.

>   - The lines with the highlighted prefix and the remark `New` did not exist in the earlier version and have been added in the current version.

> HOLD

>   The `HOLD` command is available for the current version of an object. Placing a member in `HOLD` status means that it is not counted as an existing version and is not automatically deleted as further versions of the member are created.

>   #### Example: Set version number to n

>   The `HOLD` command accepts a function parameter `VV=n` in order to set the version number to n instead of incrementing it by 1.

>       HOLD N  MBE(MYPROG), VV=7

>   sets the version number to 7 if the current version is less than seven.

>   As a result of the `HOLD` command, the version number (`VV` value) is increased by 1 or set to the value passed as `VV` parameter, and the modification level (`MM` value) is set to `00`. Further `HOLD` operations on the member further increase the version number.

>   #### Example: Issue HOLD for current version (with prompting)

>   The `HOLD` command can be issued for the current version as line command from a list of versions, or from any system screen as function command. For example, the command

>       HOLD NV MBE(MYPROG)

>   opens the following prompt window:

>       +------------------------------------------------+
>       ! HOLD-NATVER:                                   !
>       ! Library       ===> MBE                         !
>       ! Member        ===> MYPROG                      !
>       ! Date          ===> 93/08/03-11:53              !
>       +------------------------------------------------+

>   Only the current version is selected. Press ENTER to confirm.

>   #### Example: Issue HOLD for current version (without prompting)

>   The command

>       HOLD N MBE(MYPROG)

>   holds the current version of Natural member `MYPROG` without prompting.

#### Reason for Change

When updating a member with versioning active, you can indicate a reason for changing the member in either of the following ways. In either case, the reason given appears in the field headed `CHANGE REASON` in the list of versions for the member (see the examples of lists of versions above).

1. When saving the new version of the member, add the reason as parameter to the `SAVE` or `STOW` command, for example:

       STOW 'Referenced program names changed'

2. If the library is in the list of versioned libraries, ask your system administrator to add the string `REASON` to the library name. Every time you then issue the `SAVE` or `STOW` command, a window opens prompting you to add the reason for the change.

If you are authorized to change the `CHANGE REASON`, you can also use the `CH` line command.

#### Editing and Saving Previous Versions

Earlier versions of a member are available in `BROWSE` mode only (no modifications possible, see the description of the `BROWSE` command above). When displaying an earlier version of a member in Editor format, you can use the Editor `CREATE` command to save the version under a different name in the object library.

You must mark the first and last lines of the block in the member you wish to save with the Editor line command `CC` and enter the command:

    CREATE newname

in the command line. Press ENTER to create a new member with the specified name. You can edit and maintain the new member as any other member.

Alternatively, you can use multi-session mode to copy all or part of an earlier version into a new or existing member using the Editor `CC` line command to mark the block to be copied, and the Editor `A`, `B` or `O` line commands in the target member to mark the place where the text is to be entered.

Another alternative is to delete all versions created after the version you want to reactivate. This automatically makes the required version the current version.

Note
If you update a versioned Natural or PDS member with an editor outside of Natural, all versioning data for the member is lost.

### Recovery

Natural provides a comfortable recovery facility for lost files after an abnormal termination or system crash. You must have `RECOVERY ON` as a default either in your user profile or specified for your current edit session.

In your user profile, you can also specify the number of modified lines required before an automatic backup is performed (see the section Profile Maintenance).

If you lose files for any reason, Natural notifies you with a message at your next logon, asking you to list the recovery files. This automatic check for recovery files can be switched off in the User Defaults section of the Profile. This significantly reduces the time required for Natural initialization (see the `NO RECOVER` option in section Profile Maintenance). If you issue the `RECOVERY` command (an implicit `LIST REC`), you are presented with a list of recovery files. You can enter either of the following line commands in the input field preceding any file name:

Command | Meaning
--- | ---
`D` | Delete the file.
`E` | Re-edit the recovered file. The file appears as recovered at the last checkpoint.

If more than one file is to be recovered, you can re-edit one file. After saving it, issue the `END` command (usually assigned to PF3) to return to the list of recovered files and you can re-edit the next file.

See also the subsection Recovery Files in section Common Objects.

### Copying Objects

Natural provides a `COPY` command which allows you to copy a selected object in a number of ways:

1. Copy and store an object under a different name in the same object library, for example:

       COPY N NATLIB(PROG1),NATLIB(PROG2)

   copies Natural member `PROG1` from library `NATLIB` to Natural member `PROG2` in the same library.

2. Copy and store an object under the same or a different name in another library of the same object type, for example:

       COPY N NATLIB(PROG1),NEWLIB(PROG2)

   copies Natural member `PROG1` from library `NATLIB` to Natural member `PROG2` in the library `NEWLIB`.

3. Copy and store an object on another computer (if you have a multi-CPU environment), for example:

       COPY N NATLIB(PROG1),P PDSLIB(PROG2) NODE=155

   copies the Natural member `PROG1` from the library `NATLIB` as the member `PROG2` to the PDS library `PDSLIB` on Node 155.

4. Copy and store multiple members to another library, for example

       COPY P PDSLIB(ISP*),NEWLIB

   copies all PDS members in the library `PDSLIB` that start with `ISP` to the PDS library `NEWLIB`. The same functionality is also available for other object types (Natural objects, etc.).

   Note
   In Examples 1, 2 and 3, the copy operation is not performed if the member `PROG2` already exists in the target library. In Example 4, for each member name starting with `ISP` and already occurring both in source and target libraries, the user will be prompted to decide whether or not the member is to be replaced.

5. Copy and store an object as another object type; if the target object already exists, it is overwritten, for example:

       COPY P PDSLIB(MYMEM),N NATLIB(PROG1),REP

   copies the PDS member `MYMEM` from the library `PDSLIB` to the Natural library `NATLIB` as the member `PROG1`. The same functionality is also available for other object types, for example copying a Natural member to a z/OS member, or vice versa.

When using function command syntax as in the above examples, you are prompted to select valid options in selection windows should you omit any required parameter, making the `COPY` command easy to use even without knowledge of the complete command syntax.

For example, the command

    COPY PDS,NAT

prompts you first for the PDS member to be copied, then for the Natural object as destination.

If the new object name already exists in the target library, you can specify whether the existing member is to be retained or deleted (overwritten) by entering `Y` (overwrite) or `N` (retain) in the target specification window.

The `COPY` command can also be issued from the source object's Entry Panel, with object parameters entered in the input fields. Prompt windows then prompt you to specify the target object type and identifiers.

Under z/OS, if the target dataset of a `COPY D <dataset name>` command does not exist, you are prompted for a file allocation.

Note
Not every object can be stored as any other object type. For example, a Natural program cannot be copied as a job SYSOUT file. Most object types can be source objects, but use as target is restricted to those objects that can be edited, except for module CSECTs, recovery files, menus, Natural error messages, and Predict descriptions. The selection windows displayed while executing the `COPY` command list valid values only.

### Printing Objects

Objects that can be edited and saved can also be printed in a number of ways.

1. Issue the `PR` line command for an object from a list of object names;

2. Issue the `PRINT` function command from the object's Entry Panel with identifiers in the parameter input fields to print the object;

3. Issue the `PRINT` function command from any system screen in the format

       PRINT object-type object-parameters,function-parameters

   where the object parameters depend on the object type (see the description of the required object type).

   Function parameters can consist of the following:

   Parameter | Meaning
   --- | ---
   `ASIS` | Valid from an Editor session only: prints the whole Editor session, including header, PF key line, etc. For more details see the subsection Printing from an Editor Session.
   `CONTROL / CC` | Honors any ASA or machine code control characters. No additional headers are printed.
   `printer-name` | Name of the printer. This printer overrides the printer specified in your user profile.
   `NOCONTROL / NO` | Deactivates automatic carriage control when printing Natural objects or job SYSOUT files.
   `WORKPOOL` | Writes the output to the user workpool.

   Or the following keyword parameters can be used:

   Parameter | Meaning
   --- | ---
   `PRINTER` | Name of the printer.
   `DRIVER` | Specify the name of a printer control character table as defined in the Natural `NTCC` macro, or under Com-plete you can specify the name of a logical output driver routine, which can perform additional output formatting during printing.
   `FORM` | Specify a printout form specification.
   `NAME` | Specify a list name for the printout.
   `DISP` | Specify the disposition of the printout:
   `D` or `DEL` | Delete after printing (default).
   `H` or `HOLD` | Hold printout, do not print.
   `K` or `KEEP` | Keep after processing.
   `L` or `LEAV` | Leave in spool queue after printing.
   `COPIES` | You can specify the number of additional printouts.
   `PS` | Specify the number of lines per page you want for this printout.
   `SUPPRESS` | If you enter `Y`, Natural does not print header information or generate form feeds.
   `NOM` | `NOM=YES` indicates that the extended Entire Output Management interface is used for printing. For further information, see the subsection Natural ISPF Parameters in section System Configuration of the Natural ISPF Administration Guide.

#### Example:

    PRINT NAT T1M1, PRINTER=DAEPR1 COPIES=3 PS=20

In addition to printing Natural objects you can also print help texts currently displayed on the screen. Just enter the `PRINT` command from your help screen.

Note
Carriage control when printing Natural objects or SYSOUT files is automatic (see the `NO` function parameter).

The user workpool can be used as destination for various types of output: macro output, output of Natural programs, output from Natural facilities. For more information, see the subsection User Workpool in section Common Objects.

When printing to the user workpool is selected, the interpretation of carriage control characters is automatically switched off.

#### Example:

The command:

    PR N NSPF120(MYPROG),NO

prints Natural object `MYPROG` in library `NSPF120` at the default printer without automatic carriage control.

The hardcopy device at which the output is printed is selected according to the following hierarchy:

- The printer specified in the function parameters;

- The printer specified in your user profile.

If an asterisk wildcard (*) is specified as printer name, a window opens after you issue the `PRINT` command prompting you for the printer name and other printer parameters. The data entered in this window become the defaults for the next `PRINT` command prompting in your Natural session:

       -------------------------- NATURAL ISPF MAIN MENU -----------------------------
       OPTION  ===> PRINT N NSPF120(MYPROG),*
                                                                     Userid   BRY
                    +---------Print parameters----------+            Time     12:21:35
          0    PROF !                                   !            Terminal DAELC630
          1    NATU ! Enter printer  : ________         !            Library  BRY
          2    VIEW ! Lines per page : 60               !  Views     Node     148
          3    ERRO ! Interpret CC   :                  ! es
          4    PRED ! Suppress Header:                  !
          5    WORK ! Listname       : ________         !
          6    CONT ! Form           : ________         !
                    ! Disp           : ____  (D/H/K/L)  !
          7    JOBS ! Copies         :         (0-255)  ! z/OS)
          8    PDS  ! Log.-Driver    : ________         !
          9    DATA +-----------------------------------+
          10   JOBS       - Display JOBS status and data

The input fields are described below.

- If no printer is specified in your user profile, the group profile is searched for a printer: for example, if your user ID is `ABC`, profile `AB*` is searched, then `A*`, and then `*`;

- If no printer is specified in your user group profile, the printer specified in your TP environment is used;

- If no printer is specified in your TP environment, the printer assigned to `NATURAL PRINTER 2` is used (see the Natural profile parameter `PRINTER`);

If none of the above is found, you are notified by an error message.

Meaning of the input fields:

Field | Meaning
--- | ---
`Enter printer` | Enter printer name (this can also be `Workpool`).
`Lines per page` | Number of lines to be printed on a page before a page break.
`Interpret CC` | Specifies whether ASA or machine control characters, if they appear in the printout, are honored (`Y` or `N`).
`Suppress Header` | If you enter `Y`, Natural does not print header information or generate form feeds.
`Listname` | Specify a name of the printout.
`Form` | Specify a printout form.
`Disp` | Specify the disposition of the printout:
`D` or `DEL` | Delete after printing (default).
`H` or `HOLD` | Hold printout, do not print.
`K` or `KEEP` | Keep after processing.
`L` or `LEAV` | Leave in spool queue after printing.
`Copies` | Specify number of copies (maximum is 255).
`Log.-Driver` | Specify the name of a profile form, that is, the name of a printer control character table as defined in the `NTCC` macro (see the Natural Parameter Reference for more information); or: Specify the name of a logical output driver routine to perform additional output formatting during printing. Note If you want to use the logical output drivers under Software AG's TP monitor Com-plete, ask your administrator to activate the special `USPOOL` interface with `APPLYMOD 22`.

#### Printing from an Editor Session

1. Issue the `PRINT` command from an Editor session with the object in `EDIT` or `BROWSE` mode to print the member;

2. Use the Editor line command `P` to print the selected line, or mark the first and the last lines of a block of text with the Editor `PP` line command to print the block from the member;

Note
When issuing the `PRINT` command from an Editor session, the current boundary settings (`BNDS` Editor command) are respected: only the data within the set boundaries are printed.

When issuing a `PRINT` command from an Editor session, you can use the special parameter `ASIS` as follows:

    PRINT,ASIS

- If you have a printer defined in your Natural profile, the whole Editor session is printed as it would appear on your screen.

- If you have an asterisk defined as printer in your Natural profile, you are prompted for the printout parameters:

         BROWSE-NAT:NSPFEXAM(IDB-ADRP)-Program->Struct ----------------- Columns 001 072
          COMMAND===> print,asis                                         SCROLL===> CSR
         ****** *** +-----------Print parameters------------+ **************************
         000010 * E !                                       ! a window:
         000020 *   ! Lines per page    : 60                ! pplication logic
         000030 *   ! Take linesize from                    ! or messages only
         000040 *   !   edit session    : X                 !
         000050 DEF !   or screensize   :                   !
         000060 LOC ! Print prefix      : X                 !
         000070 LOC ! Enter printer     : DAEPRT12          !
         000080 1 A ! Listname          : ________          !
         000090   2 ! Form              : ________          !
         000100   2 ! Disp              : L___   (D/H/K/L)  !
         000110   2 ! Copies            :          (1-255)  !
         000120   2 ! Log.-Driver       : ________          !
         000130   2 ! Print via NOM     :          (Y/N)    !
         000140 1 K +---------------------------------------+
         000150   2 PERSONNEL-ID
         000160   2 NAME
         000170   2 ADDRESS-LINE  (1:2)
         000180   2 COUNTRY
         000190 1 #FUNK  (A1)
         Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
               Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

  Meaning of the input fields:

  Field | Meaning
  --- | ---
  `Lines per page` | Number of lines to be printed on a page before a page break.
  `Take linesize from edit session` | Mark this field if the line length of the printout is to correspond to the length of the edit session (this might be more than 80).
  `or screensize` | Mark this field if the line length of the printout is to correspond to the line length of your screen.
  `Print prefix` | Mark this field if you want the prefix area (line numbers, labels, etc.) printed.
  `Enter printer` | Enter printer name (this can also be `Workpool`).
  `Listname` | Specify a name of the printout.
  `Form` | Specify a printout form.
  `Disp` | Specify the disposition of the printout:
  `D` or `DEL` | Delete after printing (default).
  `H` or `HOLD` | Hold printout, do not print.
  `K` or `KEEP` | Keep after processing.
  `L` or `LEAV` | Leave in spool queue after printing.
  `Copies` | Specify number of copies (maximum is 255).
  `Log.-Driver` | Specify the name of a profile form, that is, the name of a printer control character table as defined in the `NTCC` macro (see the Natural Parameter Reference for more information); or: Specify the name of a logical output driver routine to perform additional output formatting during printing. Note If you want to use the logical output drivers under Software AG's TP monitor Com-plete ask your administrator to activate the special `USPOOL` interface with `APPLYMOD 22`.
  `Print via NOM` | Enter `Y` to use the extended interface between Natural and Entire Output Management.

### Natural Interface to External Environments

Natural interfaces to the PC environment and to Software AG's Office System Con-nect. You can transfer Natural objects to PC files and Con-nect cabinets, and you can transfer PC files and Con-nect documents to Natural object libraries (PDS, Natural, CA Panvalet, CA Librarian, etc.).

To perform these functions, Natural provides the `EXPORT` and `IMPORT` function commands.

> EXPORT

>   You can issue the `EXPORT` command in any of the following ways:

>   - As a function command from any Natural screen, with parameters specifying the external environment and identifiers for the object to be transferred; if any parameter is missing, selection windows prompt you for valid items;

>   - As a command from an edit session with a Natural object, with a parameter specifying the destination; destination Con-nect is specified as `CONNECT` or `CNT`, destination PC is specified as `PC`;

>   - As a line command (`EX`) from a list of Natural objects; selection windows prompt you for destination and target identifiers.

> IMPORT

>   The `IMPORT` command is a local command issued from an edit session with any Natural object that can be edited.

>   The following subsections illustrate some examples of using the Natural interface to the PC and Con-nect environments.

> DOWNLOAD / UPLOAD

>   In addition to the `EXPORT` and `IMPORT` commands, which usually handle text only, the `DOWNLOAD` and `UPLOAD` commands also handle binary data. Currently they are available for Natural objects and sources as well as data areas and maps, views and PDS members.

>   All PC files created with the Natural `DOWNLOAD` command can be processed by the `UPLOAD` command as described in the section Command Reference.

#### Exporting a Natural Object to Con-nect

To export a Natural object (PDS member, Natural program, View, sequential dataset, SYSOUT file, workpool entry, library list) to Con-nect, send it to another user or both, enter the following command in the command line and press ENTER:

    EXPORT object-name object-parameters, TARGET=CNT target-parameters

Or, if you are in an Editor session, enter the following command in the command line and press ENTER:

    EXPORT CNT

A window opens.

##### Example:

The command:

    EX P MY.ONLY.SOURCE(MYMEM),TARGET=CNT NAME=MYDOC SEND=MYBOSS

stores the PDS member `MYMEM` from the library `MY.ONLY.SOURCE` as document `MYDOC` in Con-nect and sends a copy to the user `MYBOSS`.

Natural notifies you with a message of the successful export operation. If a new document is created, it can be maintained within Con-nect as any other Con-nect document (see the Con-nect documentation).

#### Exporting Part of an Object to Con-nect

To export only part of a Natural object, open an `EDIT` session with the object and mark the required block of data with two `CC` Editor line commands, then issue the command `EXPORT CNT`. The following window opens:

       EDIT-NAT:NSPFHELP(LOGOFF)-Text->Report-Free-45K --------------- Columns 001 072
        COMMAND===> export cnt                                         SCROLL===> CSR
       ****** ****************************** top of data *****************************
       000010 &H Session Command: LOGOFF
       000020 &U MAIN
       000030 +------------------Export document to CON-NECT-------------------+
       CC0040 !                                                                !
       000050 !  Cabinet:         GHH_____                                     !
       000060 !  Password:                                                     !
       000070 !                                                                !
       000080 !  Create document: ________________________________             !
       000090 !   and/or Send to: ____________________ ____________________    !
       000100 !                   ____________________ ____________________    !
       000110 !  Description/Subject                                           !
       000120 !  ____________________________________________________________  !
       000130 !  ____________________________________________________________  !
       000140 !  ____________________________________________________________  !
       000150 !  ____________________________________________________________  !
       000160 +----------------------------------------------------------------+
       CC0170 The LOGOFF command can be concatenated with any valid NATURAL command.
       000180 Examples:
       000190 &L
       000200   #LOGOFF;FIN
       000210   #LOGOFF IMM;FIN

You can store the object as a document in Con-nect, send it as a message to one or more Con-nect users, or both.

Meaning of the input fields:

Field | Keyword | Meaning
--- | --- | ---
`Cabinet` | `CABINET` | Required. Name of the Con-nect cabinet in which the object is to be stored as a document.
`Password` | `PASSWORD` | Required, if Con-nect password is needed to access the cabinet.
`Create document` | `NAME` or `DESTINATION` | Document name under which the object is to be stored. Required for filing the Natural object as a Con-nect document. (Not required for the `SEND` function.)
`and/or Send to` | `SEND` | To send the Natural object as a message to Inbaskets of other Con-nect users, enter at least one recipient. You can specify up to four user IDs. (Not required when only storing object as document.)
`Description/Subject` |  | Optional description of object. Required for sending the Natural object as a message to other Con-nect users.

Note
If you specify document name, up to four user IDs as well as the subject, the Natural object is both filed as a document in the specified cabinet and sent to the Inbasket of the specified users.

Having specified the Con-nect destination, press ENTER. Natural notifies you with a message of the successful export operation. If a new document is created, it can be maintained within Con-nect as any other Con-nect document (see the Con-nect documentation).

See also the description of the `EXPORT` command as described in the section Command Reference.

#### Importing a Con-nect Document

To import a Con-nect document into Natural, you can start an edit session with the Natural Editor for the required object type. When the Editor screen is displayed on your screen, enter the command:

    IMPORT CNT

in the Editor direct command line and press ENTER. This opens a window in which you must specify the Con-nect document to be transferred:

      EDIT-PDS:MBE.COMN.SOURCE(DOCUMENT)------------------------------columns-001-072-
       COMMAND===> import cnt                                         SCROLL===> CSR
      ****** ****************************** top of data *****************************
      ''''''
      ''''''
      ''''''
      ''''''
      ''''''      Cabinet    ________
      ''''''      Password
      ''''''      Name       ________________________________
                  Mark for Notes/Encl. _
      ''''''
      ''''''
      ''''''
      ''''''
      ''''''
      ''''''
      ''''''
      ''''''
      ''''''
      ''''''
      ****** **************************** bottom of data ****************************
      Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
            Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

Meaning of the input fields:

Field | Keyword | Meaning
--- | --- | ---
`Cabinet` | `CABINET` | Name of the Con-nect cabinet from which the document is to be copied.
`Password` | `PASSWORD` | If required, Con-nect password to access the cabinet.
`Name` | `NAME` | Document name.
`Mark for Notes/Encl.` |  | Mark this field if the document is to be imported with cover notes and enclosures.

Specify the Con-nect document to be transferred in the window and press ENTER.

If you are creating a new Natural object (your Editor screen is blank), the document is loaded into the data area of the Editor screen. If you wish to include the document in an existing object, Natural asks you to position the document with the message Import is pending. You must mark the line after which you wish to insert the document with the `A` line command, or the line before which you wish to insert the document with the `B` line command.

Any document transferred to Natural can be edited, stored and maintained as any other Natural object.

#### Using the Natural Interface to the PC Environment

If Entire Connection is installed at your site, you can use a PC to emulate a mainframe terminal. You can transfer files between the PC and Natural using the `IMPORT` and `EXPORT` function commands.

After logging on to Natural from the PC, you must issue the Natural terminal command

    %+

from the Natural Main Menu. The terminal command `%+` sets the Natural system variable `*DEVICE` to PC (see the Entire Connection documentation for more information).

The following subsections describe how to export Natural objects and how to import PC files in more detail.

#### Exporting a Natural Object to the PC

To export (download) a Natural object (PDS member, Natural program, view, sequential dataset, SYSOUT file, workpool entry, library list) to the PC, enter the following command in the command line and press ENTER:

    EXPORT object-name object-parameters, TARGET=PC DESTINATION=<ilename.ext

If you omit the `DESTINATION` parameter, a window opens at the bottom of the screen, that prompts you to specify the name under which the object is to be stored on the PC. Enter a name for the new file and press ENTER.

Note
To download only part of a Natural object, open an `EDIT` session with the object and mark the required block of data with two `CC` Editor line commands, then issue the command `EXPORT PC`.

You are informed of the successful download operation with a message. You can check the result of your download operation by returning to MS-DOS and issuing the `DIR` command or the `TYPE <filename>` command.

To export Natural objects in binary format, Natural views or z/OS load modules, use the `DOWNLOAD` command as described in section Command Reference.

##### Examples:

- The command:

      EX P MY.ONLY.SOURCE(MYMEM),PC

  opens a window in which you can enter the PC file name under which the PDS member `MYMEM` in library `MY.ONLY.SOURCE` is to be downloaded.

- The command:

      EX P MY.ONLY.SOURCE(MYMEM),TARGET=PC DESTINATION=MYFILE.NCD

  downloads the PDS member `MYMEM` from library `MY.ONLY.SOURCE` to the PC and stores it in `MYFILE.NCD` without prompting.

See also the description of the `EXPORT` command in section Command Reference.

#### Importing a PC File into Natural

To import (upload) a PC file into Natural, you must start an edit session with the Natural Editor for the required object type. (Do not forget to signal to Natural that you are working from a PC by entering the percent sign followed by the plus sign: `%+`).

When the Editor screen is displayed, enter the command:

    IMPORT  PC, NAME=myfile.ncd

in the Editor command line and press ENTER. If the `NAME` parameter is omitted, a window opens in which you are prompted for the PC file name to be uploaded. Enter the file name in the window and press ENTER.

If you are creating a new Natural object (your Editor screen is blank), the file is loaded into the data area of the Editor screen. If you wish to include the file into an existing object, Natural asks you to position the document with the message Import is pending. You must mark the line after which you wish to insert the document with an `A` line command, or the line before which you wish to insert the document with a `B` line command.

Any PC file transferred to Natural can be edited, stored and maintained as any other Natural object.

To import Natural objects in binary format, Natural Views or z/OS load modules, use the `UPLOAD` command as described in the section Command Reference.

### Message Switching

Messages can be sent to TSO, TIAM or Com-plete users with the `SEND` command issued from any screen. This opens the following window:

       ----------------------- NATURAL OBJECTS - ENTRY PANEL -------------------------
       COMMAND ===> send

          Library       ===> NSPFEXAM
          Member        ===> *
          +-------------------------------------------------------------------------+
          !                                                                         !
          !  Send to : ________   ________   ________   ________   ________         !
          !  Node    : 148                                                          !
          !  Text    :                                                              !
          !  ______________________________________________________________________ !
          !                                                                         !
          +-------------------------------------------------------------------------+

       Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
             Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

Meaning of the input fields:

Field | Meaning
--- | ---
`Send to` | Specify up to five destination user IDs.
`Node` | Node number of destination.
`Text` | Message text.

### Using the Calculator

The `CALC` session command invokes the ISPF calculator:

       EDIT-PDS:MBE.COMN.SOURCE(ISPIDB) ---------------- +--------------------------+2
        COMMAND===> calc                                 !                          !
       000022                                            !             PF-Keys      !
       000023 Incompatibility:. The previous version who !             1 Help       !
       000024                   prefix an suffix, this v !             2 Command    !
       000025                                            !             5 Print      !
       000026 Examples -       DATA-FORMAT ******C       !             7 Up         !
       000027                  DATA-FORMAT = /*,*/    /* !             8 Down       !
       000028                                            !             9 Mode(NHD)  !
       000029                                            !               NUMERIC    !
       000030 Get Data                                   !             10 Left      !
       000031 --------                                   !             11 Right     !
       000032 Syntax   -       GET-DATA   ( USING <local !             12 Clear     !
       000033                             <var-name> ..  ! =========== ------------ !
       000034                  END-GET                   !           0              !
       000035                                            !             <--Input---- !
       000036 Where    -      <local-name> =  Name of lo !             <  Examples: !
       000037                 <var-name>   =  var-name(< !             <  12*33+5   !
       000038                 <index-definition> =   (n) !             <  -         !
       000039                 <index-definition> =   (n) !             <  126 / 2   !
       000040 Explanation     GET-DATA will restore vari !             <  +452      !
       000041                 value of SAVE-DATA, from t !             <  *A0 + H10 !
       000042                 the fields are taken from  !             <----------- !
       000043                 their  name explicity.     +--------------------------+

The calculator appears as a window on your screen and consists of two parts:

The bottom half of the calculator window is the input area into which you can enter the problem to be computed. You can enter numbers in the same line or in consecutive lines, as long as the numbers are preceded by the appropriate operator. Valid operators are:

- `+` for addition (default);

- `-` for subtraction;

- `*` for multiplications;

- `/` for divisions.

Numbers can be entered as numerical digits or in hexadecimal format. If the data entered in the input line contains more than one operator, these will be evaluated from left to right, disregarding the arithmetic processing order.

After you have entered a computing problem in the input area and pressed ENTER, the numbers reappear in the top half of the calculator in the order you entered them, preceded by the operator. The solution appears directly under the line separating the top from the bottom half. Note that you can modify values on the calculator to make corrections to the problem. The solution is immediately updated after you press ENTER.

When the calculator is displayed on your screen, you can perform certain functions using the following PF keys:

PF Key | Explanation
--- | ---
PF1 | Display help text on the input area and paper area of the calculator.
PF2 | Use the calculation result as NSPF command: a window opens with the problem solution in it. You can use the solution to form an NSPF command which is executed when you press ENTER. This is useful for example, if you want to find a hexadecimal result in a dump.
PF3 | Close the calculator window, content is kept.
PF5 | Print the contents of the calculation (destination can also be the workpool).
PF7 | Scroll up list of the numbers in top half.
PF8 | Scroll down list of the numbers in top half.
PF9 | Toggle display among numerical digits, hexadecimal format, and numerical digits with two places after the decimal.
PF10 | Move the calculator window to the left.
PF11 | Move the calculator window to the right.
PF12 | Clear the calculator for the next computation.

### Using the Macro Facility

Natural provides a facility with which source can be generated automatically, relieving you of much routine editing work, and eliminating editing errors. This feature is useful when writing programs with a similar structure but with different content.

The macro feature is an extension of the Natural language and consists of special processing statements executed when the program is compiled, as well as variables in source lines substituted by valid values at compilation time. These special processing lines and variables are distinguished in the source by typing the macro character as first character in the line.

As a simple example of macro processing lines and variables, if you define the following macro:

    0010 § MOVE 'PERSONNEL' to #FILE-NAME (A32)
    0020 § MOVE 'NAME'      to #KEY       (A32)
    0030 READ §#FILE-NAME by §#KEY

the following source line is generated at compilation time:

    READ PERSONNEL BY NAME

By varying the values, a variety of source lines can be created from the same "skeleton" macro. You can use this macro feature in Natural in a variety of ways:

1. Macro objects:
   Macro objects are a special type of Natural object and can be accessed and maintained as any other Natural object (specify `TYPE=MACRO`). They contain macro processing lines and macro variables and can be used to generate Natural programs, or they can be referenced from other Natural objects to generate text lines;

2. Inline macros:
   Other Natural objects (e.g. Natural programs, PDS members, etc.) can use macro variables in their source. They can also reference a macro object using the special `INCLUDE-MACRO <name>` statement. The variables are substituted and the specified macro object is executed, and the generated lines are included in the source when the object is compiled (Natural) or submitted (non-Natural);

3. Edit macros:
   When starting an edit session with a Natural object (Natural program, PDS member, etc.), you can specify a macro object to be used as a model for the new edit session. The specified macro is executed and the generated lines written to the new edit session. The lines generated in this way are protected, but you can reserve some places in the macro object in which you can add your own code after the macro is invoked as an edit macro.

The generated output of objects that use the macro facility is written to the user workpool, where it can be checked and further handled (for full details and examples, see the section Macro Facility in the Natural ISPF Programmer's Guide).

### Executing Command Scripts

This subsection explains the commands which can be used in, or in conjunction with, command scripts:

- PLAY Function Command
- RECORD Session Command
- PAUSE Session Command
- Scripts in the User Workpool
- CONTINUE Session Command
- Example:
- MACPARM Session Command
- MESSAGE Session Command
- REMARK Session Command
- Generating Scripts using a Macro

You will find examples of how to generate scripts using a macro under Generating Scripts using a Macro.

#### PLAY Function Command

Natural commands can be written and stored in a member. Such a member is called a command script. The script can be executed with the `PLAY` function command. The commands are then executed sequentially. Scripts executed by the `PLAY` command are written to the User Workpool (see the subsection Scripts in the User Workpool).

Command scripts can be stored as any of the following object types:

- Natural object

- PDS member

- Workpool output file (see below)

- Macro

##### Example:

Assume Natural member `MYPROCA` in library `MYLIB` contains the following lines:

    ED MYLIB(PROGA);STOW;END
    ED MYLIB(PROGB);STOW;END
    ED MYLIB(PROGC);STOW;END

The command:

    PLAY MYLIB(MYPROCA)

edits and stows the Natural programs `PROGA`, `PROGB` and `PROGC`.

- A script that has been interrupted by an included `PAUSE` command (see below) can be cancelled by the session command `PLAY OFF`. This command also deletes the workpool entry (see the subsection Scripts in the User Workpool).

- If an invalid command is detected in a command script during execution, and the script does not contain a `CONTINUE` statement, the script is stopped automatically and the invalid command is displayed in the Natural command line. You can correct the faulty command and reexecute it by pressing ENTER. You can then continue the script by issuing the `PAUSE` session command (see below).

- If one of the played commands results in an error message (for example, if program `PROGB` in the above example does not contain correct Natural source, the same logic applies as for invalid commands.

- A command script held in a PDS member may not contain line numbers within the member's lines (for example, in columns 73 to 80). Thus, when editing such a command script, it is recommended that you switch off the number mode of the Editor, either with the profile settings or by issuing one of the Editor commands `AUTOREN OFF` or `UNREN`. You should be aware that the line numbers could have been inherited unintentionally when copying lines from one `EDIT` session to another with the line commands mentioned in this documentation. Line numbers contained in script lines could result in unpredictable error messages during command script execution.

- It is possible to use nested `PLAY` commands in a command script. The contents of a member to be played is always entered at the top of the `##PLAY` workpool session.

##### Example:

Assume the member `EX1` contains the following lines:

    EDIT NAT MYPROG
    PLAY NAT EXPLAY(CHG-AB)
    EDIT NAT MYPROG1
    PLAY NAT EXPLAY(CHG-AB)

and assume member `CHG-AB` contains the following lines:

    CHANGE 'A' 'B' all
    STOW
    END

The command:

    PLAY EX1

starts an edit session with Natural member `MYPROG`, plays the commands in `CHG-AB`, and only then is the command `EDIT MYPROG1` processed.

- In the `COMMAND` field in your user profile, you can specify a command that is executed every time you start Natural. You can specify a `PLAY` command in this profile field to start a command script when you log on (see also the description of the `COMMAND` field in the User Defaults subsection of section Profile Maintenance).

- It might be useful when writing a command script to start it with `RECORD ON` and finish it with `RECORD OFF`. This causes all messages to be recorded in the User Workpool (see the `RECORD` session command below).

#### RECORD Session Command

You can record Natural commands using the `RECORD` session command. After you have issued the `RECORD` session command, all ensuing commands are recorded until you issue the `RECORD OFF` session command. The recorded commands can be found in the User Workpool in member `##RECORD`. This member can be `PLAY`ed.

If a command issued during the recording session causes a message, the message is also recorded in the User Workpool member `##RECORD`, preceded by two asterisks (**). The message is ignored when the member is executed with the `PLAY` command.

#### PAUSE Session Command

In some cases it is useful to interrupt a script being executed, for example in order to manipulate some data manually, and then continue executing the script. This can be done by writing the session command `PAUSE` in the script. When the script is executing, it stops at the place the `PAUSE` command was entered. To continue the script, simply issue the `PAUSE` command manually.

##### Example:

Assume the member `MYPROCB` contains the following lines:

    EDIT MYJOB
    PAUSE
    SUB
    FOLLOW
    CAN

The command:

    PLAY MYPROCB

starts an edit session with the member `MYJOB` and then stops in order to allow modification of the JCL. If you then issue the `PAUSE` command from the Natural command line, the JCL is submitted, job status messages are displayed (`FOLLOW` command) and the edit session is cancelled.

Note
The `PAUSE` command must always be the last command or the only command in a script line.

#### Scripts in the User Workpool

A script which is executed by the `PLAY` command is stored in the User Workpool in an entry named `##PLAY`. When a script is interrupted by a `PAUSE` command or an error, the lines not yet executed are in the workpool member `##PLAY` and can be modified.

#### CONTINUE Session Command

The `CONTINUE` command can be used in command scripts to gain more flexible control in error situations. If no `CONTINUE` statement is in the command script, the script is set to `PAUSE` mode after an error.

If a `CONTINUE` statement (which can be compared to a label) is in the script, the following actions are taken:

1. `RECORD ON` is set internally if not activated by the user.

2. The command causing the error and the message is recorded.

3. All lines of the script until the next `CONTINUE` command are deleted and execution of these lines is skipped.

4. Processing continues with the next `CONTINUE` statement. All following statements are executed.

5. Termination resets `RECORD` to its previous value and informs the user if an error has occurred.

#### Example:

    KEYS 3 PAUSE
    HELP VERIFY
    MESSAGE 7480
    TECH
    ........
    CONTINUE
    REMARK PROCESSING WILL CONTINUE HERE AFTER ERROR
    KEYS 3 END

The above script modifies the user profile. By using the `CONTINUE` command it makes sure that, after execution of the script, PF3 is reset to its default value from the user profile, even if errors have occurred during execution of the script.

#### MACPARM Session Command

The `MACPARM` command is used in command scripts to put data on the Natural stack which is read by a macro using an input statement later in the command script.

This avoids prompting by the macro for parameters, when using macros in command scripts. The `MACPARM` command must be the only command in a source line.

The command format is:

    MACPARM p1

Explanation of parameters:

Parameter | Meaning
--- | ---
`p1` | Maximum length of this parameter is 50 bytes and it can contain blanks.

##### Examples:

The commands:

    MACPARM LS PDS JW(A*)
    PLAY MAC MAC1

pass the command `LS PDS JW(*)` to macro `MAC1`.

Another useful example can be found in the member `VERIFY` in the Natural Example Library.

#### MESSAGE Session Command

The `MESSAGE` command can be used in command scripts to display a text during execution of a script on the screen and to interrupt the active command script. The `MESSAGE` command must be the only command in a source line.

The command format is:

    MESSAGE p0,p1,...pn

Explanation of parameters:

Parameter | Meaning
--- | ---
`p0` | Must be a 4-digit error message number. First, the user library `SYSISPFU` is searched for the message text. If it does not exist, it is taken from the system library `SYSISPS1`.
`p1,...pn` | Optional parameters which are used to replace variable parameters (`:1: . . . . . . :n:`) in the text. Parameters must usually be separated with your parameter delimiter, usually a comma (,) and can contain blanks.

##### Examples:

The command:

    MESSAGE 6812,MYPROG

results in the following message, if no text for this number is available in the user library `SYSISPFU`:

    Member MYPROG not found

The command:

    MESSAGE 6809,Please enter some text

results in the following message, if no text for this number is available in the user library `SYSISPFU`:

    Please enter some text

Another useful example can be found in member `VERIFY` in the Natural Example Library.

#### REMARK Session Command

The `REMARK` command is used in command scripts to document the command script.The `REMARK` command must be the only command in a source line.

The command format is:

    REMARK text

##### Example:

    REMARK The following command extracts all members
    REMARK including the string Adabas
    LIST PDS JW(*) SC=Adabas

#### Generating Scripts using a Macro

A command script can be generated by a macro. With this mechanism, scripts can be created dynamically.

##### Example: Generate prompt for CHANGE

For example, executing the following macro with the `PLAY` command generates a prompt for a `CHANGE` command to be used on a member, with a choice of a `STOW` or `SAVE` command after the change is made:

    § RESET #MEMBER(A8) #FROM(A16) #TO(A16) #STOW(A1)
    § INPUT(AD=MI) 'Change' #FROM 'To' #TO 'in member' #MEMBER
    §            / 'Stow?' #STOW
    EDIT NAT §#MEMBER
    CHANGE '§#FROM'  '§#TO' all
    § IF #STOW NE ' ' DO
    STOW
    § DOEND
    § ELSE DO
    SAVE
    § DOEND
    END

##### Example: Installation Verification

The following macro generates a command script which verifies Natural installation. It also provides you with a working example of how the commands `CONTINUE`, `MACPARM`, `MESSAGE` and `REMARK` function:

    § DEFINE DATA LOCAL
    § 1 #SUB-SYSTEM (A3)
    § 1 #SUB-SYSTEM-INDEX(N1)
    § 1 #SUBSYS-ARRAY (4)
    §   2 #SUBSYS-LONG (A10) INIT <'NATURAL', 'z/OS'>
    §   2 REDEFINE #SUBSYS-LONG
    §     3 #SUBSYS-SHORT (A3)
    § END-DEFINE
    § IF *DATA GT 0
    §   INPUT   #SUB-SYSTEM
    §   EXAMINE #SUB-SYSTEM TRANSLATE INTO UPPER
    §   EXAMINE #SUBSYS-SHORT(*) FOR #SUB-SYSTEM INDEX #SUB-SYSTEM-INDEX
    § END-IF
    § IF #SUB-SYSTEM-INDEX EQ 0
    §   #SUB-SYSTEM-INDEX := 1    /* NATURAL is default
    § END-IF
    § #SUB-SYSTEM := #SUBSYS-SHORT(#SUB-SYSTEM-INDEX)
    KEYS 3 PAUSE
    HELP VERIFY
    MESSAGE 7480,§#SUBSYS-LONG(#SUB-SYSTEM-INDEX)
    TECH
    END
    § IF #SUB-SYSTEM-INDEX EQ 1
    PLAY NAT VERIFYO
    § ELSE
    MACPARM §#SUB-SYSTEM-INDEX
    PLAY MAC VERIFYS
    § END-IF
    CONTINUE
    REMARK Processing will continue here after error
    REMARK and pf3 will be reset to its initial profile value
    KEYS 3 INITIAL
    RECORD OFF

## Additional Features in Lists

The following topics are covered below:

- ALL Command for Lists

- LAYOUT Command for Lists

- RELIST Command for Lists

- SORT Command for Lists

### ALL Command for Lists

In most of the Natural `LIST` sessions, the command `ALL` is available to execute a command or command sequence for all objects shown in the list. This is done internally by generating a command script and executing (playing) it.

#### Examples:

Command | Function
--- | ---
`ALL ED` | The command `EDIT` is executed for all members of the list. If an `END` command usually assigned to PF3 is entered, the current `EDIT` session is terminated and an `EDIT` session for the next member from the list is opened.
`ALL PG *` | All objects from the list (probably jobs) are purged.
`ALL 'ED *;STOW;END'` | All members are edited and compiled.
`ALL ED +` | A window opens for entering the command string. For further information see the example below.

The command string must be included in quotes, if it contains command or parameter delimiters like semicolon (;) or comma ( , ). The following special characters can be used inside the command string:

Character | Meaning
--- | ---
`+` | A plus sign entered as last character indicates that command string is not yet complete. A window opens where further data can be entered.
`*` | An asterisk indicates position where the full object name is inserted into the command.
`:1:` | A number in colons indicates position where the first part of the object name is inserted into the command.
`:2:` | As above but second part.
`:3:` | As above but third part.

Notes:

1. The last three notations are not available with most of the Natural objects because the full object name which identifies an object consists of one word only. However, there are exceptions like Librarian members which are identified with name and type.
2. For the commands to operate on selected objects listed, use the Editor command `EXCLUDE` or the Editor line commands `X` or `XX` to reduce the set of displayed lines. A subsequent `ALL` command operates only on the displayed lines, not on the excluded ones.

#### Example: ALL Prompt Window

The prompt window opens, if it is requested by a plus sign as last character of the command string or when Natural detects that more than a simple command has been entered. Simple commands consist of only one Natural function code or function code and wildcard character (*):

    ALL ED
    ALL PG *

Simple commands are executed immediately, and if the wildcard character (*) is not entered, it is automatically generated at the end of the command string, so `ALL ED` and `ALL ED *` are treated identically.

The following is an example of the prompt window that opens after entering the command:

    ALL ED +

       LIST-NAT:NSPFHELP(*)/SCAN=&V211 ---------------- Row 0 of 113 - Columns 010 076
        COMMAND===> ALL ED +                                           SCROLL===> CSR
          MEMBER            PGMTYPE     SM S/C  NUM FIRST FOUND
       ** ******************************** top of list *******************************
       +------------------------List command propagator-------------------------+
       ! ENTER without any changes will start processing.                       !
       ! Command       :  EDIT *____________________________________________    !
       !                  ______________________________                        !
       ! Generate only :  _                                                     !
       !                                                                        !
       +------------------------------------------------------------------------+
          BD-FCBTY          Text           S      1 &V211 I

You can abort processing by pressing PF3. If you mark `Generate only`, then the command script is generated only to the Natural workpool. Execution is not started. The generated script can be executed later with the `PAUSE` command or can be saved in a member for execution with the `PLAY` command.

For example, if you modify the `Command` field of the above window to contain:

    EDIT *;PLAY NAT SCRIPTS(REPLA-01);SAVE;END

and press ENTER twice, all members listed will be edited, modified according to the Editor commands contained in the Natural member `REPLA-01` of the library `SCRIPTS` and updated without any further manual activity.

### LAYOUT Command for Lists

This feature applies to any list of objects displayed in Natural.

When a list of Natural objects is displayed, you can change the layout of the list for better viewing according to your own criteria. This is done by issuing the local command `LAYOUT` from the list. This opens the following window:

    LIST-NAT: +----------List Layout definition-----------+ f 531 - Columns 010 076
     COMMAND= !  Select fields and sort sequence:         !         SCROLL===> PAGE
       MEMBER !                                           !    DATE     TIME  VV.MM
    ** ****** !     Field-name                     AD Seq ! ***********************
       ISP--- !  1_ MEMBER                          _  __ !    20000406 14:23
       ISP--- !  __ PGMTYPE                         _  __ !    20030109 15:35
       ISP--R !  __ SM                              _  __ !    20070326 15:17
       ISP--R !  __ S/C                             _  __ !    20020904 16:57
       ISP--R !  __ VERSION                         _  __ !    20070615 14:31
       ISP--S !  __ USERID                          _  __ !    20070615 14:39
       ISP--Z !  __ DATE     TIME                   _  __ !    20020904 16:56
       ISP--Z !  __ VV.MM                           _  __ !    20030324 11:28
       ISP--Z !                                           !    20020904 16:56
       ISP--Z !                                           !    20020904 16:56
       ISP--Z !                                           !    20020904 16:56
       ISP-AC !  Enter (Y) to delete layout    _          !    20020904 16:57
       ISP-AC !  Entr-PF3--PF7--PF8--                     !    20020904 16:56
       ISP-AC !  Down End  Up   Down                      !    20020904 16:57
       ISP-AC +-------------------------------------------+    20020904 16:56
       ISP-AIVP          Program     R  S/C 3.1 0006  JWO      20020904 16:57
       ISP-AS-C          Copycode    S  S   3.1 0002  ISP242   20000406 14:23
       ISP-AS1C          Copycode    S  S   3.1 0002  ISP242   20000406 14:23
    Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
          Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

Meaning of the column headings in the window:

Column | Meaning
--- | ---
`Field name` | These are the column headings for the list. You can change their order from left to right by assigning sequence numbers to them. For example, enter `1` before `MEMBER` to display it as the first column on the left, enter `2` before `PGMTYPE` to display it as the second column, etc. If you do not assign a sequence number to a column heading, the heading does not appear in the display. Note that some sequence numbers are not modifiable due to internal processing reasons.
`AD Seq` | These two fields allow you to define the sorting hierarchy. In the `AD` field, enter `A` for ascending order or `D` for descending order. In the `Seq` field, enter a sequence number for the sorting hierarchy. For example, enter `1` in the `Seq` field of the `USERID` line and `2` in the `DATE/TIME` line to sort the list first according to user ID and then for each user according to date and time. You can specify up to 5 fields to define the sorting hierarchy.

- The defined layout can optionally be stored in your user profile. Once you have defined the desired layout and attempt to close the window with PF3, another prompt window asks you whether the layout is to be stored or not. `Y` stores the layout in your user profile, `N` keeps the layout for the current session only.

- You can delete a defined layout by issuing the `LAYOUT` command from the respective list and entering `Y` in the field prompted ENTER (`Y`) to delete layout. The list is then displayed in the standard format when regenerated.

#### Example:

Assuming you have generated a list of Natural objects using the command:

    LIST NAT NSPF82(ISP-*)

and from the list you have issued the `LAYOUT` command. You are interested in listing members by type, user ID and date. You could fill the prompt screen as follows:

    LIST-NAT: +----------List Layout definition-----------+ f 531 - Columns 010 076
     COMMAND= !  Select fields and sort sequence:         !         SCROLL===> PAGE
       MEMBER !                                           !    DATE     TIME  VV.MM
    ** ****** !     Field-name                     AD Seq ! ***********************
       ISP--- !  1_ MEMBER                          A  4_ !    20000406 14:23
       ISP--- !  2_ PGMTYPE                         A  1_ !    20030109 15:35
       ISP--R !  __ SM                              _  __ !    20070326 15:17
       ISP--R !  __ S/C                             _  __ !    20020904 16:57
       ISP--R !  __ VERSION                         _  __ !    20070615 14:31
       ISP--S !  3_ USERID                          A  2_ !    20070615 14:39
       ISP--Z !  4_ DATE     TIME                   D  3_ !    20020904 16:56
       ISP--Z !  __ VV.MM                           _  __ !    20030324 11:28
       ISP--Z !                                           !    20020904 16:56
       ISP--Z !                                           !    20020904 16:56
       ISP--Z !                                           !    20020904 16:56
       ISP-AC !  Enter (Y) to delete layout    _          !    20020904 16:57
       ISP-AC !  Entr-PF3--PF7--PF8--                     !    20020904 16:56
       ISP-AC !  Down End  Up   Down                      !    20020904 16:57
       ISP-AC +-------------------------------------------+    20020904 16:56
       ISP-AIVP          Program     R  S/C 3.1 0006  JWO      20020904 16:57
       ISP-AS-C          Copycode    S  S   3.1 0002  ISP242   20000406 14:23
       ISP-AS1C          Copycode    S  S   3.1 0002  ISP242   20000406 14:23
    Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
          Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

If you close the window and repeat the `LIST` command, the list is displayed in the new format: the columns from left to right are `MEMBER (1)`, `PGMTYPE (2)`, `USERID (3)` and `DATE/TIME (4)`. The other columns are not displayed. The data is sorted first by `PGMTYPE (1)`, then `USERID (2)`, `DATE/TIME (3)` and `MEMBER (4)`. `DATE/TIME` is in descending order, the other columns in ascending order.

An example of the resulting list is illustrated on the next page.

This list shows the result of the procedure described above, with a `FIND MAP` command issued to display `MAP` type objects:

    LIST-NAT:NSPF82(ISP-*)M ------------------------- Row 0 of 66 - Columns 010 076
     COMMAND===>                                                    SCROLL===> PAGE
       MEMBER            PGMTYPE     USERID   DATE     TIME
    ** ******************************** top of list *******************************
       ISP-POP1          Map         BLI      20110119 14:50
       ISP-TE11          Map         BLI      20110117 15:15
       ISP-TEC1          Map         BLI      20110117 15:00
       ISP-SPA1          Map         BLI      20081029 11:44
       ISP-SPR1          Map         BLI      20081029 11:43
       ISP-RLO1          Map         FHI      20060621 10:46
       ISP-BC5M          Map         FHI      20031113 08:58
       ISP-MEC1          Map         FHI      20031113 08:58
       ISP-BC-M          Map         FHI      20031113 08:57
       ISP-ACM1          Map         JWO      20020904 16:56
       ISP-ACT1          Map         JWO      20020904 16:56
       ISP-BPS1          Map         JWO      20020904 16:56
       ISP-BR-M          Map         JWO      20020904 16:56
       ISP-BRK1          Map         JWO      20020904 16:56
       ISP-BRR1          Map         JWO      20020904 16:56
       ISP-BRV1          Map         JWO      20020904 16:56
       ISP-BR5M          Map         JWO      20020904 16:56
       ISP-CAB1          Map         JWO      20020904 16:56
    Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
          Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

### RELIST Command for Lists

In most of the Natural `LIST` sessions, the command `RELIST` is available to rebuild the list to reflect changes from line commands like `DELETE`, `RENAME` or `EDIT`.

This command does not apply to so-called refreshable lists like list of jobs, which are rebuilt

#### Example:

This example shows a list of PDS members after execution of the `DELETE` line command on a number of members:

       LIST-PDS:BRY.COMN.SOURCE(H*) ------------------------ >>> Member H11000 deleted
        COMMAND===>                                                    SCROLL===> CSR
          MEMBER            VV.MM  CREATED  MODIFIED TIME  SIZE   INIT   TID   ID
       ** ******************************** top of list *******************************
          HELP              01.04  19970202 19970202 15:19     71     51       BRY
          HELP1             01.99  19970203 19970208 17:27    153     63       BRY
          HPSPOOL           01.03  19980112 19980112 16:55     44     10       GW
          H11000   *Deleted 01.01  19970318 19970318 14:42     20     20       BRY
          H11002   *Deleted 01.01  19970318 19970318 14:43     29     29       BRY
          H1100210 *Deleted 01.01  19970318 19970318 14:44     19     19       BRY
          H11004   *Deleted 01.01  19970318 19970318 14:44     12     12       BRY
          H11006   *Deleted 01.01  19970318 19970318 14:45     15     15       BRY
          H11007   *Deleted 01.01  19970318 19970318 14:45     21     21       BRY

Below you can see the result of the `RELIST` command:

       LIST-PDS:BRY.COMN.SOURCE(H*) --------------------- Row 0 of 3 - Columns 010 076
        COMMAND===>                                                    SCROLL===> CSR
          MEMBER            VV.MM  CREATED  MODIFIED TIME  SIZE   INIT   TID   ID
       ** ******************************** top of list *******************************
          HELP              01.04  19970202 19970202 15:19     71     51       BRY
          HELP1             01.99  19970203 19970208 17:27    153     63       BRY
          HPSPOOL           01.03  19980112 19980112 16:55     44     10       GW
       ** ****************************** bottom of list ******************************

### SORT Command for Lists

When displaying lists of objects, you can use the Editor `SORT` command with special parameters:

    SORT column-header a/d

where:

Parameter | Meaning
--- | ---
`column header` | String of the column header according to which the items in the list are to be sorted.
`a` | Ascending order (default).
`d` | Descending order.

#### Examples:

Command | Function
--- | ---
`SORT DATE` | Sorts the list in ascending order according to date, that is, the item edited last is at the bottom of the list. The `SORT` command with no parameters assumes the first column is to be taken.
`SORT :C` | If you use the `SORT` command in lists frequently, you should define a PF key with this command. Then, to perform the sort, just move the cursor to the relevant column header and press the assigned PF key.

### On this page

- Handling and Navigational Features
- Functional Features
- Additional Features in Lists