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 DCL command procedure or execute an executable program on OpenVMS from within a Natural program.

This document covers the following topics:

Syntax

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

Parameters

command

Command to be executed under control of the operating system command interpreter. 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:

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

Natural manipulates return codes from the control interpreter in the following way:

  • Even numbers are interpreted as error codes and are retained unchanged.

  • Odd numbers are interpreted as success codes and are converted to 0.

The following return code values are available:

Return Code Description
0 Command successfully executed.
4 Illegal SHCMD parameter specified.
All other codes Command has returned an error.

Examples

Execute a DCL command procedure from within Natural:

CALL 'SHCMD' '@MYDCL.COM'

Execute an executable program from within Natural:

CALL 'SHCMD' 'MYPROGRAM.EXE'

After executing the DIRECTORY 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' 'DIRECTORY' 'SCREENIO'

Retrieve the return code by using the RET function: 

DEFINE DATA LOCAL 
  1 rc (I4) 
END-DEFINE 
CALL 'SHCMD' '' '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

Execute the DCL command procedure MYSUCCESS.COM. Natural will recognize that the command procedure returns an odd return number and assumes success by mapping the exit code 15 to 0.

DCL command procedure MYSUCCESS.COM: 

$ WRITE SYS$OUTPUT "DCL returns SUCCESS"
$ EXIT 15

Executing the DCL command procedure MYERROR.COM, Natural would recognize that the command procedure returns an even return number, assumes an error and leaves the number unchanged.

DCL command procedure MYERROR.COM: 

$ WRITE SYS$OUTPUT "DCL returns ERROR"
$ EXIT 14