
Natural for Mainframes	Version 8.2.5 for Mainframes	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— Statements —

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. 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 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
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

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT