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, call a shell script or execute an executable program on Linux 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 to be executed under control of the operating system command shell. Natural waits until the command is completed and then Natural returns control back to the Natural program. For more information, see Examples below.
`option` | `option` describes how the command should be executed. This parameter is optional. The following options are available: `SCREENIO` `NOSCREENIO` See Parameter Options below.

## Parameter Options

The following parameter options are available:

Option | Description
--- | ---
`NOSCREENIO` | This option is used to hide the output generated by the command. The hidden output is redirected to the null device.
`SCREENIO` | This option is used to refresh the Natural screen output after the command is completed.

Note
The options `SCREENIO` and `NOSCREENIO` 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 | Command shell return code.

## Examples

Execute a command shell from within Natural:

    CALL 'SHCMD' 'myshell.sh'

Execute an executable program from within Natural:

    CALL 'SHCMD' 'myprogram'

Execute the operating system command `ls` on Linux to list the contents of a directory:

    CALL 'SHCMD' 'ls'

After executing the `ls` command, you will recognize that the output generated by this command has changed the last Natural screen output. You have to press the refresh-screen key to clear the screen. To do this automatically, you can specify the `SCREENIO` option:

    CALL 'SHCMD' 'ls' 'SCREENIO'

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

    DEFINE DATA LOCAL
      1 rc (I4)
    END-DEFINE
    CALL 'SHCMD' 'lsDIRECTORY' 'SCREENIO'
    ASSIGN rc = RET( 'SHCMD' )            /* retrieve return code
    IF rc <> 0 THEN
       IF rc = 4 THEN
         WRITE NOTITLE 'Illegal option specified'
       ELSE
         WRITE NOTITLE 'Command not executed successfully (rc=' rc ')'
       END-IF
     ELSE
         WRITE NOTITLE 'Command executed successfully'
    END-IF
    END

### On this page

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