PROCESS COMMAND
ACTION |
|||||||
USING |
PROCESSOR-NAME= operand1 |
||||||
COMMAND-LINE
(index[:index])=operand2 |
|||||||
GIVING
|
RESULT-FIELD
(index[:index])
|
(see Syntax Note) | |||||
RETURN-CODE |
|||||||
[NATURAL-ERROR ]
|
PROCESS COMMAND
ACTION |
|||||
GET |
USING
|
PROCESSOR-NAME= operand1 |
|||
GETSET-FIELD-NAME= operand3 |
|||||
GIVING
|
GETSET-FIELD-VALUE |
(see Syntax Note) | |||
[NATURAL-ERROR ]
|
PROCESS COMMAND
ACTION |
||
SET |
USING |
PROCESSOR-NAME= operand1 |
GETSET-FIELD-NAME= operand3 |
||
GETSET-FIELD-VALUE= operand4 |
||
[ GIVING
|
NATURAL-ERROR ] (see
Syntax
Note)
|
PROCESS COMMAND
ACTION |
|
CLOSE |
[ GIVING
NATURAL-ERROR ] (see
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
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.
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.)
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.
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 |
---|---|
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:
In addition, the runtime action definitions If the field Note: |
EXEC
|
EXEC Action:
Only Note: See also Example 1 - PROCESS COMMAND ACTION EXEC. |
TEXT
|
TEXT Action:
This text is the same as that entered in the keyword editor or action editor
of the For further information, see the following sections under Input Values for TEXT Actions: Note: |
HELP
|
HELP Action:
For further information, see the following sections under Input Values for HELP Actions: Note: |
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 If any See also Example 2 - PROCESS COMMAND ACTION CLOSE. |
GIVING |
GIVING Option:
This option is only required in reporting mode and if no The This means that in structured mode all field defined in the Note: |
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 |
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-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:
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.
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 ofRESULT-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 commandADD USER
is to be returned, the command lines 1, 2, 3, and 6 must be blank; the command line 4 must contain the text stringADD
, and the command line 5 must contain the text stringUSER
.
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.
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 fieldsRESULT-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 optionS
is used, the function is returned inRESULT-FIELD (1:3)
.Example:
Input: Output: Command Line 1: IFN Command Line 2: 0001048578 Result-Field 1: DISPLAY INVOICE
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.
/* 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
/* 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