SHELL Function

  • Article

[This topic is prerelease documentation and is subject to change in future releases. Blank topics are included as placeholders. There may be some display and formatting issues until the look and feel is finalized.]

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.

Property Value/Return Value

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, then include the return value. Omit the return value if you want to run the external program non-modally. For example, if all that 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, then 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.

Remarks

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.

Example

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 run time. 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.
  }
}

See Also

Reference

APPLICATIONPATH Function
COMMANDLINE Function
ENVIRON Function
GUIALLOWED Function
HYPERLINK Function
OSVERSION Function
SLEEP Function
TEMPORARYPATH Function

Other Resources

CONTEXTURL Function