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 explanations 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:
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