Issuing Operating System Commands from within a Natural Program

#### Search Results

Search

# Issuing Operating System Commands from within a Natural Program

The Natural user exit `SHCMD` can be used to issue an operating system command from within a Natural program.

This document covers the following topics:

- Syntax

- Parameters

- Parameter Options

- Return Codes

- Examples

## Syntax

`CALL` 'SHCMD' 'command' ['option']

## Parameters

`command` | `command` is to be executed by the operating system. To execute commands (such as `DIR` for directory or `DEL` for delete) you have to specify the system command interpreter as well. For more information, see Examples below.
`option` | `option` describes how the command should be executed. This parameter is optional. The following options are available: `ASYNCH` `NOSCREENIO` `SYNCH` (default) See Parameter Options below.

## Parameter Options

The following parameter options are available:

Option | Description
--- | ---
`ASYNCH` | Natural does not wait until the command is completely executed. This kind of processing is named asynchronous processing.
`NOSCREENIO` | This option is used to hide the output generated by the command. The hidden output is redirected to the null device.
`SYNCH` | Natural waits until the command is completed. This kind of processing is named synchronous processing and is set by default.

Note
The options `ASYNCH` and `SYNCH` may be not set at the same time.

## Return Codes

The following return code values are available:

Return Code | Description
--- | ---
`0` | Command successfully executed.
`4` | Illegal SHCMD parameter specified.
All other codes | Operating-system-dependent error code.

## Examples

Execute operating system command `DIR` to view a directory:

    CALL 'SHCMD''CMD.EXE /C DIR'

Retrieve the return code by using the Natural function `RET`:

    RESET rc (I4)
    CALL 'SHCMD''CMD.EXE /C DIR'
    rc = RET( 'SHCMD' )                   /* retrieve return code
    IF rc <> 0 THEN                       /* in case of an error
    DISPLAY "Error occurred during SHCMD" /* display an error message

Execute a command which includes blanks within the command by enclosing the command with quotation marks.

The following example executes Microsoft Excel.

    RESET #cmd (A253)
    MOVE '"C:\Program Files\Microsoft Office\Office\EXCEL.EXE"' to #cmd
    CALL "SHCMD" #cmd "ASYNCH"

In this case, parameter `TQ` (translate quotation marks) has to be `OFF`, otherwise the quotation marks have been removed.

To be independent of the `TQ` parameter, use the hexadecimal ASCII code of quotation marks (H'22') and append it at the beginning and the end of the command. The following example demonstrates this:

    RESET #cmd (A253)
    MOVE H'22' - "C:\Program Files\Microsoft Office\Office\EXCEL.EXE" - H'22' to #cmd
    CALL "SHCMD" #cmd "ASYNCH"

### On this page

- Syntax
- Parameters
- Parameter Options
- Return Codes
- Examples