PROCESS COMMAND

#### Search Results

Search

# PROCESS COMMAND

#### CHECK | EXEC | TEXT | HELP Syntax:

`PROCESS COMMAND ACTION`
| `CHECK` `EXEC` `TEXT` `HELP` |  | `USING` | `PROCESSOR-NAME=`operand1
| `COMMAND-LINE` (index[:index])=operand2
`GIVING` | `RESULT-FIELD` (index[:index]) | (see Syntax Note)
| `RETURN-CODE` |
[`NATURAL-ERROR`]

#### GET Syntax:

`PROCESS COMMAND ACTION`
`GET` | `USING` | `PROCESSOR-NAME=`operand1
|  | `GETSET-FIELD-NAME=`operand3
`GIVING` | `GETSET-FIELD-VALUE` | (see Syntax Note)
| [`NATURAL-ERROR`] |

#### SET Syntax:

`PROCESS COMMAND ACTION`
`SET` | `USING` | `PROCESSOR-NAME=`operand1
|  | `GETSET-FIELD-NAME=`operand3
|  | `GETSET-FIELD-VALUE=`operand4
| `[``GIVING` | `NATURAL-ERROR``]` (see Syntax Note)

#### CLOSE Syntax:

`PROCESS COMMAND ACTION`
`CLOSE` | `[``GIVING` `NATURAL-ERROR``]` (see Syntax Note)

#### Syntax Note:

The `GIVING` option is only required in the reporting mode and if no `VIEW OF COMMAND` has been defined in the `DEFINE DATA` statement.

This document covers the following topics:

- Function

- Syntax Description

- Examples

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Belongs to Function Group: Invoking Programs and Routines

## Function

Once a Natural Command Processor has been created using the Natural utility `SYSNCP`, it can be invoked from a Natural program using the `PROCESS COMMAND` statement.

For details on how to create a Natural Command Processor, refer to the SYSNCP Utility documentation.

#### DDM Used for Command Processing

Important
The word `COMMAND` in the `PROCESS COMMAND` statement is in fact the name of a view. The name of the view that is used need not necessarily be `COMMAND`; however, we recommend the use of `COMMAND` because there exists a DDM (data definition module) that is also called `COMMAND`. This DDM must be referenced within the `DEFINE DATA` statement, for example `COMMAND VIEW OF COMMAND`.

The DDM `COMMAND` has been created specifically for use in conjunction with the `PROCESS COMMAND` statement:

    DB:    1 File:    1 - COMMAND                          Default Sequence: ?

      TYL  DB  NAME                             F LENG  S D   REMARKS
      ---  --  -------------------------------- - ----  - -  ------------------------
        1  AA  PROCESSOR-NAME                   A    8  N D DE    USING
      M 1  AB  COMMAND-LINE                     A   80  N D MU/DE USING
        1  AF  GETSET-FIELD-NAME                A   32  N D DE    USING
        1  BA  NATURAL-ERROR                    N  4.0  N         GIVING
        1  BB  RETURN-CODE                      A    4  N         GIVING
      M 1  BC  RESULT-FIELD                     A   80  N   MU    GIVING
        1  BD  GETSET-FIELD-VALUE               A   32  N D       USING; GIVING
      ***** DDM OUTPUT TERMINATED ******

The fields contained in the DDM correspond to the fields used in the `PROCESS COMMAND` statement. They are explained in Syntax Element Description.

Note
To avoid possible compilation or runtime errors, make sure that the DDM named `COMMAND` is cataloged as type `C` (field `DDM Type` on the SYSDDM Menu) before you use it. (If you re-catalog the DDM, any DBID/FNR specification in the `SYSDDM` utility will be ignored.)

#### Security Considerations

With Natural Security, it is possible to restrict the usage of certain keywords and/or functions which are defined in a Command Processor. Keywords and/or functions can be allowed/disallowed for a specific user or group of users. See the Natural Security documentation for details.

## Syntax Description

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` | C | S |  |  |  | A |  |  |  |  |  |  |  |  |  |  |  |  | no | no
`operand2` | C | S | A | G |  | A |  | N |  |  |  |  |  |  |  |  |  |  | no | no
`operand3` | C | S |  |  |  | A |  | N |  |  |  |  |  |  |  |  |  |  | no | no
`operand4` | C | S |  |  |  | A |  | N | P | I |  |  |  |  |  |  |  |  | no | no

Syntax Element Description:

Syntax Element | Description
--- | ---
`CHECK` | CHECK Action: `CHECK` is used as a precautionary measure to determine if a command is executable with the statement `PROCESS COMMAND EXEC`. It works as follows: for the given Command Processor name, a runtime check is performed in two steps: It is checked whether the Command Processor exists in the current library or one of its steplibs; The content of the command line `COMMAND-LINE (1)` is analyzed to determine whether it is acceptable. In addition, the runtime action definitions `R`, `M` and `1-9` are written into `RESULT-FIELD (1:9)`. If the field `NATURAL-ERROR` is specified in the view or in the `GIVING` option, it returns the error code. If this field is not available and the command analysis fails, a Natural system error occurs. Note No `CHECK` is required if you want to perform an `EXEC` action. The `CHECK` is included in an `EXEC` operation.
`EXEC` | EXEC Action: `EXEC` works exactly the same as `CHECK` with the addition that the runtime actions are executed as specified in the runtime action editor. Only `COMMAND-LINE (1)` is needed. You can use up to 9 occurrences of `RESULT-FIELD` (however, for optimum performance, you should not use more occurrences than you really need). Note `EXEC` is the only action which can be used to leave the currently active program. This is the case when the runtime action definition contains a `FETCH` or `STOP` statement. See also Example 1 - PROCESS COMMAND ACTION EXEC.
`TEXT` | TEXT Action: `TEXT` delivers general information about the Command Processor and text associated with a keyword or function. This text is the same as that entered in the keyword editor or action editor of the `SYSNCP` utility during Command Processor definition. For further information, see the following sections under Input Values for TEXT Actions: TEXT for General Information TEXT for Keyword Information TEXT for Function Information Note To access texts for keywords and functions, you must have specified `Y` in the field `Catalog user texts` on the Processor Header Maintenance 3 screen of the `SYSNCP` utility, see the section Miscellaneous Options - Header 3.
`HELP` | HELP Action: `HELP` returns a list of all valid keywords, synonyms, and functions for the purpose of, for example, the creation of online help windows. This list is contained in the field(s) of `RESULT-FIELD`. The type of help returned is dependent on the content of the command lines. `COMMAND-LINE (1)` must contain the search criteria. `COMMAND-LINE (2)`, if specified, must contain the start value or a search value. `COMMAND-LINE (3)`, if specified, must contain a start value. For further information, see the following sections under Input Values for HELP Actions: HELP for Keywords HELP for Synonyms HELP for Global Functions HELP for Local Functions HELP for IKN HELP for IFN Note For optimum performance, the number of occurrences of the field `RESULT-FIELD` should not exceed the number of lines to be displayed on the screen. At least one occurrence must be used.
`GET` | GET Action: `GET` reads internal Command Processor information and current Command Processor settings from the dynamically allocated `NCPWORK` buffer.
`SET` | SET Action: `SET` modifies internal Command Processor settings in the `NCPWORK` buffer.
`CLOSE` | CLOSE Action: `CLOSE` terminates the use of the Command Processor and releases the Command Processor buffer. When the Command Processor is used during a session and is not released with `CLOSE`, then there exists a buffer named `NCPWORK` in your thread. The runtime part of the Command Processor requires this buffer; it can be released using the statement `PROCESS COMMAND ACTION CLOSE`. If any `PROCESS COMMAND` statement follows this statement, then the Command Processor buffer will be opened again. See also Example 2 - PROCESS COMMAND ACTION CLOSE.
`GIVING` | GIVING Option: This option is only required in reporting mode and if no `VIEW OF COMMAND` has been defined in the `DEFINE DATA` statement. The `GIVING` option is not available in structured mode, because there exists an implicit `GIVING` option made up of all fields specified in the `DEFINE DATA` statement, which are usually referenced in the `GIVING` option for the reporting mode. This means that in structured mode all field defined in the `GIVING` option must be defined in the `DEFINE DATA` statement. Note Specified in the `GIVING` option are fields to be filled by the Command Processor as a result of the processing of any action.
`PROCESSOR-NAME` | The name of the Command Processor to be used for processing. The Command Processor specified must be cataloged.
`COMMAND-LINE` | The command line to be processed by a `CHECK` or an `EXEC` action, or the keyword/command for which user text or help text is to be returned to the program by a `TEXT` or `HELP` action. Note that this field can contain more than one occurrence.
`RESULT-FIELD` | Contains information resulting from the use of options that can be specified within a runtime action defined for a Command Processor function (see Runtime Actions in the Natural `SYSNCP` utility). Note that this field can contain more than one occurrence.
`RETURN-CODE` | The return code of an operation resulting from an `EXEC` or a `CHECK` action as specified within a Runtime Actions definition (see the Natural `SYSNCP` utility).
`NATURAL-ERROR` | The Natural error returned for a `PROCESS COMMAND` action. We recommend that you use this field in the `DEFINE DATA` statement as it returns the Natural error code for the Command Processor. When the field is absent, Natural runtime error processing is triggered if an error occurs.
`GETSET-FIELD-NAME` | The name of the constant or variable that is read when a `GET` action is performed or that is written with a `SET` action. For a list of possible values for `GETSET-FIELD-NAME`, see Input Values for GETSET-FIELD-NAME.
`GETSET-FIELD-VALUE` | The value of the constant or variable specified in the field `GETSET-FIELD-NAME` which is read when a `GET` action is performed or which written with a `SET` action.

This section covers the following topics:

- Input Values for GETSET-FIELD-NAME

- Input Values for TEXT Actions

- Input Values for HELP Actions

### Input Values for GETSET-FIELD-NAME

The following values can be used for the `GETSET-FIELD-NAME` field (A32):

Field Name | Format | G/S* | Content
--- | --- | --- | ---
`NAME` | A8 | G | Name of current Command Processor.
`LIBRARY` | A8 | G | Loaded from library.
`FNR` | N10 | G | Loaded from file.
`DBID` | N10 | G | Loaded from database.
`TIMESTMP` | A8 | G | Time stamp of the current Command Processor.
`COUNTER` | N10 | G | Access counter.
`BUFFER-LENGTH` | N10 | G | Bytes allocated for `NCPWORK`.
`C-DELIMITER` | A1 | G/S | Multiple command delimiter.
`DATA-DELIMITER` | A1 | G | Delimiter to precede data.
`PF-KEY` | A1 | G/S | PF key may be command (`Y/N`).
`UPPER-CASE` | A1 | G | Keywords in upper case (`Y/N`).
`UQ-KEYWORDS` | A1 | G | Keywords unique (`Y/N`).
`IMPLICIT-KEYWORD` | A1 | G/S | Identifier for implicit keyword entry.
`MIN-LEN` | N10 | G | Minimum length of keywords.
`MAX-LEN` | N10 | G | Maximum length of keywords.
`KEYWORD-SEQ` | A8 | G/S | Keyword sequence.
`ALT-KEYWORD-SEQ` | A8 | G/S | Alternative keyword sequence.
`USER-SEQUENCE` | A1 | G | User may override `KEYWORD-SEQ` (Y/N).
`CURR-LOCATION` | N10 | G/S | Current location (IFN).
`CURR-IKN1` | N10 | G/S | IKN1 of current location.
`CURR-IKN2` | N10 | G/S | IKN2 of current location.
`CURR-IKN3` | N10 | G/S | IKN3 of current location.
`CHECK-LOCATION` | N10 | G | Last checked location (IFN).
`CHECK-IKN1` | N10 | G | IKN1 of `CHECK-LOCATION`.
`CHECK-IKN2` | N10 | G | IKN2 of `CHECK-LOCATION`.
`CHECK-IKN3` | N10 | G | IKN3 of `CHECK-LOCATION`.
`TOP-IKN1` | N10 | G | IKN1 of topmost keyword.
`TOP-IKN2` | N10 | G | IKN2 of topmost keyword.
`TOP-IKN3` | N10 | G | IKN3 of topmost keyword.
`KEY1-TOTAL` | N10 | G | Number of keywords of type 1.
`KEY2-TOTAL` | N10 | G | Number of keywords of type 2.
`KEY3-TOTAL` | N10 | G | Number of keywords of type 3.
`FUNCTIONS-TOTAL` | N10 | G | Number of cataloged functions.
`LOCAL-GLOBAL-SEQ` | A8 | G/S | Local/global function validation.
`ERROR-HANDLER` | A8 | G/S | General error program.
`SECURITY` | A1 | G | Natural Security installed (`Y/N`).
`SEC-PREFETCH` | A1 | G | Natural Security data are to be read (`Y/N`) or have been read (`D` = done).
`PREFIX1` | A1 | G | Corresponds to the field Prefix Character 1 on the Processor Header Maintenance 2 screen of the `SYSNCP` utility, see the section Keyword Editor Options - Header 2.
`PREFIX2` | A1 | G | Corresponds to the field Prefix Character 2 on the Processor Header Maintenance 2 screen.
`HEX1` | A1 | G | Corresponds to the field Hex. Replacement 1 on the Processor Header Maintenance 2 screen.
`HEX2` | A1 | G | Corresponds to the field Hex. Replacement 2 on the Processor Header Maintenance 2 screen.
`DYNAMIC` | A32 | G | Dynamic part (:n:) of last error message.
`LAST` | - | G | Last command placed on top of stack as data.
`LAST-ALL` | - | G | Last commands placed on top of stack as data.
`LAST-COM` | - | G | Last command moved to `*COM`.
`MULTI` | - | G | Places the last of multiple commands as data on top of the stack.
`MULTI-COM` | - | G | Places the last of multiple commands in the system variable `*COM`.

*`G` = Field name can be used with the `GET` action.
*`S` = Field name can be used with the `SET` action.

### Input Values for TEXT Actions

The following input values are provided to return different information from a `TEXT` action:

> TEXT for General Information

>   For general information, `COMMAND-LINE (*)`; that is, all command lines, must be blank. Up to nine fields of `RESULT-FIELD` are returned containing the following information:

>   RESULT-FIELD | Format | Contents
>   --- | --- | ---
>   1 | Text (A40) | Header 1 for User Text
>   2 | Text (A40) | Header 2 for User Text
>   3 | Text (A16) | "First Entry used as" text
>   4 | Text (A16) | "Second Entry used as" text
>   5 | Text (A16) | "Third Entry used as" text
>   6 | Numeric (N3) | Number of Entry 1 Keywords
>   7 | Numeric (N3) | Number of Entry 2 Keywords
>   8 | Numeric (N3) | Number of Entry 3 Keywords
>   9 | Numeric (N7) | Number of Cataloged Functions

> TEXT for Keyword Information

>   For keyword information, `COMMAND-LINE (1)` must contain the corresponding keyword; `COMMAND-LINE (2)` can optionally contain the keyword type (1, 2, 3 or P); `COMMAND-LINE (3:6)` must be empty.

>   RESULT-FIELD | Contents | Format
>   --- | --- | ---
>   1 | Keyword comment text | Text (A40)
>   2 | Keyword in full length | Text (A16)
>   3 | Keyword in unique short form | Text (A16)
>   4 | "Keyword used as" entry | Text (A16)
>   5 | Internal keyword number (IKN) | Numeric (N4)
>   6 | Minimum length of keyword | Numeric (N2)
>   7 | Maximum length of keyword | Numeric (N2)
>   8 | Keyword type (1, 2, 3, 1S, 2S, 3S, P) | Text (A2)

> TEXT for Function Information

>   For function information, `COMMAND-LINE (1:3)` must contain the keywords which specify the wanted location. `COMMAND-LINE (4:6)` contains the keywords which specify the wanted function. For example, if information about the global command `ADD USER` is to be returned, the command lines 1, 2, 3, and 6 must be blank; the command line 4 must contain the text string `ADD`, and the command line 5 must contain the text string `USER`.

>   RESULT-FIELD | Format | Contents
>   --- | --- | ---
>   1 | Text (A40) | Text as defined with the option T in runtime action definition.
>   2 | Numeric (N10) | Internal function number (IFN) of the specified location.
>   3 | Numeric (N10) | Internal function number (IFN) of the specified function.

### Input Values for HELP Actions

The following input values are provided to return different information from a `HELP` action:

> HELP for Keywords

>   This action returns an alphabetically sorted list of keywords and/or synonyms with their internal keyword numbers (IKN).

>   Command Line | Contents
>   --- | ---
>   1 | Must begin with indicator `K`.
>   The types of keywords to be returned:
>   `*` | Keywords of all types
>   `1` | Keywords with type 1
>   `2` | Keywords with type 2
>   `3` | Keywords with type 3
>   `P` | Keywords with type P (parameter)
>   Options:
>   `I` | Return IKN in addition to keywords.
>   `T` | Show keyword partially in upper case (to show possible abbreviation).
>   `S` | Return synonyms in addition to keywords.
>   `X` | Return only synonyms of specified keywords.
>   `A` | Internal keywords are also returned.
>   `+` | Search does not include start value.
>   2 | Start value for the keyword search (optional). By default, the search begins with the start value. However, if you specify the plus (+) option, the search does not include the start value itself, but begins with the next higher value.

>   The field `RESULT-FIELD (1:n)` returns the specified list.

>   #### Examples:

>       Command Line 1:    K*X     Returns all synonyms of all keyword types.

>       Command Line 1:    K123S   Returns all keywords of type 1, 2 and 3 including synonyms.

> HELP for Synonyms

>   For a given IKN, this action returns the original keyword and all synonyms.

>   Command Line | Contents
>   --- | ---
>   1 | Must begin with the indicator `S`.
>   Option:
>   `T` | Shows keyword partially in upper case (to show possible abbreviation).
>   2 | Internal Keyword Number (IKN) of the keyword in format N4.

>   The field `RESULT-FIELD (1)` returns the original keyword. The fields `RESULT-FIELD (2:n)` return associated synonyms for this keyword.

>   Example:

>   Input: | Output:
>   --- | ---
>       Command Line 1:    S
>       Command Line 2:    1003
>       Result-Field 1:    Edit
>       Result-Field 2:    Maintain
>       Result-Field 3:    Modify

> HELP for Global Functions

>   This action returns a list of all global functions.

>   Command Line | Contents
>   --- | ---
>   1 | Must begin with the indicator `G`.
>   Options:
>   `I` | Internal Function Number (IFN) is also returned.
>   `T` | Shows keyword partially in upper case (to show possible abbreviation).
>   `S` | The keywords returned in `RESULT-FIELD` will be aligned in columns.
>   `A` | Internal keywords are also returned.
>   `1` | Only functions containing the given keyword of type 1 are to be returned.
>   `2` | Only functions containing the given keyword of type 2 are to be returned.
>   `3` | Only functions containing the given keyword of type 3 are to be returned.
>   `+` | Search does not include start value.
>   2 | Start value for global function search. Keywords must be given in sequence `123`. By default, the search begins with the start value. However, if you specify the plus (+) option, the search does not include the start value itself, but begins with the next higher value.
>   3 | Must be blank.
>   4 | To search only for global functions with a specific keyword, you specify the keyword here. If you specify a keyword, you also have to specify the keyword type (1, 2 or 3) as option (see above).

>   The field `RESULT-FIELD (1:n)` returns the specified list.

>   Example:

>   Input: | Output:
>   --- | ---
>       Command Line 1:    G
>       Command Line 2:    ADD
>       Result-Field 1:    ADD CUSTOMER
>       Result-Field 2:    ADD FILE
>       Result-Field 3:    ADD USER

> HELP for Local Functions

>   This action returns a list of all local functions for a specified location.

>   Command Line | Contents
>   --- | ---
>   1 | Must begin with the indicator `L`.
>   Options:
>   `I` | Internal Function Number (IFN) is also returned.
>   `T` | Shows keyword partially in upper case (to show possible abbreviation).
>   `S` | The keywords returned in `RESULT-FIELD` will be aligned in columns.
>   `A` | Internal keywords are also returned.
>   `1` | Only functions containing given keyword of type 1 are to be returned.
>   `2` | Only functions containing given keyword of type 2 are to be returned.
>   `3` | Only functions containing given keyword of type 3 are to be returned.
>   `C` | Only those functions are returned which are defined for the current location (command line 3 is ignored).
>   `F` | Invoke "recursive" listing of local functions; that is, all local commands that lead to the current/specified location will be returned.
>   2 | Start value for local function search (optional). Keywords must be given in sequence `123`.
>   3 | The location for which the list is to be returned. Keywords must be given in sequence `123`. If no location is specified, the current location of the Command Processor will be used.
>   4 | Keyword restriction (optional): If you specify a keyword, or an IKN with the format N4, only functions with this keyword will be returned.

>   The field `RESULT-FIELD (1:n)` returns the specified list.

> HELP for IKN

>   For any given internal keyword numbers (IKN), this action returns the original keyword.

>   Command Line | Contents
>   --- | ---
>   1 | Must start with `IKN`.
>   Options:
>   `A` | The internal keyword will be shown.
>   `T` | Shows keyword partially in upper case (to show possible abbreviation).
>   2 | The IKN to be translated, in format N4.

>   The field `RESULT-FIELD (1)` returns the keyword.

>   Example:

>   Input: | Output:
>   --- | ---
>       Command Line 1:    IKN
>       Command Line 2:    0000002002
>       Result-Field 1:    CUSTOMER

> HELP for IFN

>   For any given internal function numbers (IFN), this action returns the keywords of a function.

>   Command Line | Contents
>   --- | ---
>   1 | Must start with IFN.
>   Option:
>   `A` | Functions with internal keywords will not be suppressed.
>   2 | The IFN to be translated, in format N10.
>   3 | Further options:
>   `S` | Keywords belonging to the IFN will be returned in `RESULT-FIELD (1:3)`.
>   `T` | Shows keywords partially in upper case (to show possible abbreviations).
>   `L` | IFN will be returned if IFN is used as a location.
>   `C` | IFN will be returned if IFN is used as a command.

>   The field `RESULT-FIELD(1)` returns the function; if option `S` is used, the function is returned in `RESULT-FIELD (1:3)`.

>   Example:

>   Input: | Output:
>   --- | ---
>       Command Line 1:    IFN
>       Command Line 2:    0001048578
>       Result-Field 1:    DISPLAY INVOICE

## Examples

In addition to the example programs shown in this section, you can find example programs in the `SYSNCP` system library. These programs all begin with `EXAM`.

You can test all available `PROCESS COMMAND` actions by executing the `EXAM` program in `SYSNCP`. You can then choose an action from a menu.

- Example 1 - PROCESS COMMAND ACTION EXEC

- Example 2 - PROCESS COMMAND ACTION CLOSE

### Example 1 - PROCESS COMMAND ACTION EXEC

    /* EXAM-EXS - Example for PROCESS COMMAND ACTION EXEC (Structured Mode)
    /**********************************************************************
    DEFINE DATA LOCAL
      01 COMMAND VIEW OF COMMAND
         02 PROCESSOR-NAME
         02 COMMAND-LINE (1)
         02 NATURAL-ERROR
         02 RETURN-CODE
         02 RESULT-FIELD (1)
      01 MSG (A65) INIT <'Please enter a command.'>
    END-DEFINE
    /*
    REPEAT
      INPUT (AD=MIT' ' IP=OFF) WITH TEXT MSG
        'Example for PROCESS COMMAND ACTION EXEC (Structured Mode)' (I)
      / 'Command ==>' COMMAND-LINE (1) (AL=64)
      /*******
     PROCESS COMMAND ACTION EXEC
        USING
          PROCESSOR-NAME = 'DEMO'
          COMMAND-LINE (1) = COMMAND-LINE (1)
      /*******
      COMPRESS 'NATURAL-ERROR =' NATURAL-ERROR TO MSG
    END-REPEAT
    END

### Example 2 - PROCESS COMMAND ACTION CLOSE

    /* EXAM-CLS - Example for PROCESS COMMAND ACTION CLOSE (Structured Mode)
    /***********************************************************************
    DEFINE DATA LOCAL
      01 COMMAND VIEW OF COMMAND
    END-DEFINE
    /*
    PROCESS COMMAND ACTION CLOSE
    /*
    DEFINE WINDOW CLS
    INPUT WINDOW = 'CLS'
      'NCPWORK has just been released.'
    /*
    END

### On this page

- Function
- Syntax Description
- Examples