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

Windows offers two versions of the CMD interpreter:

  • 32-bit: C:/Windows/System32/cmd.exe

  • 64-bit: C:/Windows/Sysnative/cmd.exe

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 contains 32-bit binaries.

Note: When setting interpreter paths in RunMyJobs, you can use either forward slashes or backslashes.

By default, the CMD Definition Type uses the 32-bit interpreter. However, there are multiple ways to specify which CMD interpreter is used.

  • The /configuration/jcs/PlatformAgent/WindowsLocalInterpreterBits registry entry lets you set the overall default by specifying 32 or 64. Alternatively, you can set this entry to the path of the desired CMD executable (see above). If this registry entry is not present, the 32-bit interpreter is the overall default.

  • You can use the Process Server Parameters listed below to override the default interpreter on a given Process Server.

  • You can use Process Definition Parameters to override both the registry entry and any Process Server Parameters.

Process Server Parameters

The relevant Process Server Parameters are:

  • LocalInterpreter_CMD. You can set this Parameter to 32 for 32-bit, or 64 for 64-bit. Alternatively, you can set this Parameter to the path of the desired CMD executable (see above).
  • InterpreterWhitelist_CMD: You can set this Parameter to a regex expression that matches all interpreters you want supported. Use *. to allow any, or (for example) C:/Windows/.*/cmd.exe to allow any cmd.exe in a subfolder of C:/Windows. You can also explicitly set two interpreters, separated by a comma without a space. For example: C:/Windows/Sysnative/cmd.exe, C:/Windows/System32/cmd.exe. If you set this Parameter to an invalid value such as foo, no CMD interpreter will run because no interpreters match.

Process Definition Parameters

To override both the registry setting and the Process Server Parameters, you can set the JCS_INTERPRETER_CMD Process Definition Parameter to the path of the desired interpreter.

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:

{session}{virtual}:ops

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

{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"
)