SHELL Function

Microsoft Dynamics Nav 2009

Executes external programs and operating system commands from C/AL programs.


[ReturnCode :=] SHELL(Name[, Param, ...])

Parameters

Name

Type: Text or code

The path and name of the command. The following rules apply:

  • You can omit the drive designation if the command is located on the current drive.

  • You can omit the full path if the command is located in the current directory.

  • You can enter only the subdirectory name if the command is located in a subdirectory of the current directory.

Param

Type: Text or code

One or more optional parameters sent with the external program or command.

The parameters cannot be passed as part of the Name parameter. The Name parameter must be filled in and it must not contain any parameters except for the executable. The parameter information must be hard-coded as a text constant or as a variable.

The SHELL function has been designed so that each user can create a list of trusted executables. This list is maintained in the user’s .zup file. The way this function works depends on whether the executable is given as a text constant or as a variable.

If the name of the executable is passed to the SHELL function as a text constant then the executable is trusted and the user is not prompted to confirm that they trust the executable. This is also the case when the executable (text constant) is called with a number of other arguments that have been assigned manually.

If the name of the executable is passed to the SHELL function as a variable then the executable is not trusted and the user is prompted to confirm whether they trust the executable the first time it is called. After the user has confirmed that they trust the executable it can be called again at any time without having to confirm that it is trusted.

Type: Integer

The return value is used for the following purposes:

  • If the return value is used, then the external program will be run modally; otherwise, it will be run non-modally. For example, if you want to go to the operating system and get a directory listing and then bring that information back, include the return value. Omit the return value if you want to run the external program non-modally. For example, if all you want to do is pass information (such as a name and address) to a standardized letter that is set up in a word processor, you would omit the return value.

  • The return value can contain the return value of the external program. Since external programs can return different codes to reflect whether errors occurred during the execution of the program, the values stored in ReturnCode depend on the external program.

You can run this function modally or non-modally, depending on whether you include the return value from the external program in your code.

The SHELL function can only be used with a text constant on Microsoft Dynamics NAV Application Server.

The SHELL function is not supported in the RoleTailored client.

OBJECT Codeunit 98123 SHELL ex
{
  OBJECT-PROPERTIES
  {
    Date=30-08-04;
    Time=14:12:57;
    Modified=Yes;
    Version List=;
  }
  PROPERTIES
  {
    OnRun=BEGIN
            // The following is not trusted and will give a warning.
            ExecName := 'C:\windows\notepad.exe';
            param := 'C:\MyFile.txt';
            ret := SHELL(ExecName, param);
            // The following is trusted and will not give a warning.
            param := 'C:\MyFile.txt';
            ret := SHELL(TEXT000, param);
            // The following is not possible - will only give an error
            // message during runtime. This is also if its a TextConst:
            ExecName := 'C:\windows\notepad.exe C:\MyFile.txt';
            ret := SHELL(ExecName);
          END;
  }
  CODE
  {
    VAR
      ret@1000 : Integer;
      param@1001 : Text[30];
      TEXT000@1002 : TextConst 'ENU=C:\windows\notepad.exe';
      ExecName@1003 : Text[30];
    BEGIN
    END.
  }
}

Community Additions

ADD
Show: