Using the CMD Definition Type

For commands that interact with COM or WMI commands it is better to use the VBScript or PowerShell definition types.

Note: You must assign at least one Process Server to run CMD Process Definitions in order to use the Definition Type.

Variables and Parameters

  • Parameters to the Process can be manipulated in the CMD source simply as if they are variables, using the standard %PARAMETER% syntax.
  • The CMD language does not have actual data types. All parameter values are stored as strings. Numbers are translated automatically. Dates are sent and retrieved using the Script Date Format.
  • Out parameters are supported by setting the parameter using the set PARAMETER=VALUE syntax.

Exiting a Script

If processing of the CMD file ends by means of a hard EXIT [0] command (without the /b switch), a warning will be included in the output file and output variables will not be set. The correct ways to end the process without error and set the output variables are:

  • Running to the end of the Process Definition source.
  • Using GOTO :EOF (see HELP GOTO).
  • Using EXIT /B [0].

Returning an Error

If processing of the CMD file ends by means of a hard EXIT [<n>] command, where <n> is an integer greater than 0 (without the /b switch), the process will reach status Error and output variables will not be set. The correct way to return an error and still set the output variables is EXIT /B <n>, where <n> is an integer greater than 0. The return code will be used as the Return Code of the process.

32-Bit and 64-Bit Interpreters

By default, the 32-bit versions of the interpreters are used on Windows platforms. You can change this as follows.

  • JCS_INTERPRETER_CMD: You can use this parameter to override the default parameter by setting it to C:/Windows/Sysnative/cmd.exe for 64-bit. The default value when this parameter is nonexistent or empty, if the Process Server parameter LocalInterpreter_CMD is not set, is C:/Windows/System32/cmd.exe.
  • InterpreterWhitelist_CMD: A Process Server parameter that takes a regular expression matching all interpreters you want supported. Use .* to allow any, or C:/Windows/.*/cmd.exe} to allow any cmd.exe in a subfolder of C:/Windows. You can also explicitly specify two interpreters, separated by a comma without space (regular expressions syntax), like so: C:/Windows/Sysnative/cmd.exe,C:/Windows/System32/cmd.exe.
  • LocalInterpreter_CMD: Set this Process Server parameter to C:/Windows/Sysnative/cmd.exe for 64-bit. This parameter affects all processes for the Process Server that do not have JCS_INTERPRETER_CMD set. The default value is C:/Windows/System32/cmd.exe.
  • LocalInterpreterBits - If you set this parameter to 64, all Windows Platform Agents will use 64-Bit interpreters.

Note: In Windows 64-bit, you have to explicitly call the 32-bit binaries to access C:/Windows/Sysnative. The path does not exist for 64-bit applications. In 32-bit applications, C:/Windows/System32 is linked to C:/Windows/SYSWOW64, which contains the 32-bit windows binaries. Remember that on 64-bit Windows platforms, the System32 directory contains 64-bit binaries and SYSWOW64 is the directory containing 32-bit binaries. In other words, the number of bits is the opposite of that in the directory name.

Always use forward slashes / as a Windows path separator. Windows accepts them almost everywhere, except in some legacy MS DOS-era executables.

Background and Foreground Processes

By default, commands are executed in the background, so you will not see any dialog on the server console. If you want to display a process on-screen, use the {session} or {console} keywords in the Run As User field, followed by the credential or username and password.

  • {session}: The process runs in a RDP, Windows Terminal Server, or console session as the account specified in the credential. If no such windows user session exists, the process will fail with status Error.
  • {console}: Console session only. Console sessions are displayed on the physical monitor screen attached to the server. If the user specified by the credential is not the user that is logged on to the console, the process will fail with status Error.

These two options are useful, but they require dedicating a system to a particular account (via {console} ) or that some other means is used to ensure that a RDP session exists. It is usually better to let the Platform Agent manage RDP sessions via the built-in Windows Session support.

Note: Sessions are always for a user account. It is not possible to run session/console processes under NT Authority\LocalSystem.

Run As User Examples

Specifying a Run As User field with {session} and virtual user:

Copy 
{session}{virtual}:ops

Specifying a Run As User field with {console} and credential:

Copy 
{console}jdoe@example.corp

Examples

This example shows how to pass numeric (N1), string (S1) and date (D1) parameters to and from CMD scripts.

Copy 
set /A N1=%N1% + %N1%
rem Concatenate string
set S1=%S1% %S1%
set DTEMP=1999/12/31 23:59:59,000 GMT"
echo You said %D1%, I propose %DTEMP%
rem Set DateTime to new string value
set D1=%DTEMP%

This example shows how to return a non-zero exit code resulting in the processes going into Error status.

Copy 
set N=1
echo Exiting with value %N%.
if %N% GEQ 1 exit/b %N%

echo Not reached

This example shows how to obtain the number of free bytes on drive C on the Process Server that the process runs on.

Copy 
rem
rem Find out how many bytes are free on drive C:, and set the DIRSPACE variable
rem accordingly. This depends on "dir" writing the drive space on its last line
rem of output. We continuously overwrite the same variable until we automatically
rem leave the last value in place.
rem

for /F "usebackq tokens=3" %%x in (`dir /-C c:\`) do call :getline %%x
goto :EOF

:getline
set DIRSPACE=%1
goto :EOF

This example shows how to detect if the 32-bit executable is used. (This requires a hotfix for Windows 2003: kb942589).

Copy 
if exist c:\windows\sysnative\cmd.exe (
    echo "32-bit"
) else (
    echo "64-bit"
)