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:

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.

For further information, see the following sections under Input Values for TEXT Actions:

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:

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 parameters of this buffer may be evaluated by using the system command BUS. 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 stuctured 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

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

/* 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