A Description of the Verbose Help Output for the Process Control Command-Line Utility (296258)


The information in this article applies to:

  • Microsoft Windows 2000 Datacenter Server
This article was previously published under Q296258

SUMMARY

This article describes the verbose Help output that is available for the Process Control command-line utility.

MORE INFORMATION

The Process Control command-line utility can be used to view Help output for available command-line switches. The proccon.exe /? command can output a general Help display and the proccon.exe -? -switch command can output a more verbose display of information about that particular switch. There is no verbose output switch that can output all of the Help information at once so Microsoft has supplied this document, which is a display of the options summary that is followed by a full detail listing of all the command-line features that are available by means of the command-line Help.

This article is quite long. To easily find the detail about a particular switch, perform a page-text search for the "Switch -your_switch" string.

Options Summary

The Process Control command-line utility uses a series of switches that describe the operation to perform and the utility supplies the required data.

For Help about any switch, type: proccon -? -switch1 -switch2 ... -switchn

For example, to view the add, delete, and replace Help screens, type: proccon -? -a -d -r

General command syntax:

The following information is a summary of command-line operations only; the information does not include the detailed switches that accompany each operation. For Help on those switches, type: -? followed by the verb or the object switches, for example:

ProcCon [-c computername] [-b buffersize] [-verb] [-object] [objectdata]

Where:
  • Computername is the name of the computer to connect to (the default is the local computer).
  • Buffersize is the size of the buffer to use, in kilobytes (the range is from 2 KB to 64 KB).
  • Verb is the operation to be performed (the default is "list").
  • Object is the name of the object to operate on (usually required).
  • Objectdata is the data that is associated with the object (may be required).
Verbs:
  • -l lists objects
  • -a adds a new object
  • -r replaces an existing object
  • -u updates an existing object
  • -d deletes an existing object
  • -s swaps existing Process Alias rule entries
  • -k kills a Process Control group or a process
  • -m starts or stops the Process Control mediator process (for Help, type -m help)
  • -* inserts a comment; the entire line is ignored
  • -i enters Interactive mode
  • -f processes Process Control commands in a file (for example, -f filename)
  • -x performs a Process Control administrative command (for Help, type -? -x)
  • -? shows Help for all Process Control commands, or shows Help for a verb or object (for example, -? -v)
Objects:
  • -n or -namerules are Name (alias) rules. The index number is required data (for example, -n 7).
  • -ps or -procSummary indicate the Process rules list. Optional data is the start name.
  • -gs or -grpSummary indicate the Group rules list. Optional data is the start name.
  • -pl or -procList indicate the process list. Optional data is the start name.
  • -gl or -grpList indicate the group list. Additional data can be the start name and data flags.
  • -pd or -procDef indicate the process definition. The name of the process is required data. Additional data is the definition detail.
  • -gd or -grpDef indicate the group definition. The name of the process group is required data. Additional data is the definition detail.
  • -v or -version indicate the version or parameter information. Additional data is the new parameter.
===========================================================================

Full Detail Listing

-c
The -c switch is used to specify the target computer for ProcCon commands. The format is "-c computer-name" where computer-name is the name of the computer to connect to. The default is the local computer (which can also be selected with a period (.).

Example: "proccon.exe -c SqlServer2 ...command to execute..."

NOTES: Do not include a leading \\ on the computer name as universal naming convention (UNC) path names are not supported. In Interactive mode, computer-name is used for all future commands. Select a computer and Interactive mode with the command string "proccon.exe -c name -i". The proccon.exe service must be running on the target computer.
===========================================================================

-b
The -b switch is used to set the buffer size that is used for the ProcCon connection. There is no reason to change this size. The default is 64 KB. The format is "-b size" where size is the buffer size in kilobytes. Do not include the 'K'.

Example: "ProcCon -c computer-name -b 4 ...command to execute..."

NOTE: The buffer size is only used when you connect to a new computer. The minimum buffer size is 2 KB and the maximum size is 64 KB. If you use a smaller-sized buffer, you can have increased network traffic.
===========================================================================

-l
The -l switch is used to list ProcCon data. This switch must be followed by an object switch to show what to list. The format is '[-l[f]] -objname [arg] [grpListFlags]' where... f, which is a suffix, lists full-length names, and long names are not truncated. The -objname is the type of object to list: -n or -namerule to list process alias rules, -ps or -procsummary to list process rule summary data, -gs or -grpsummary to list grp rule summary data, -pd or -procdef to list a single process rule, -gd or -grpdef to list a single process group rule, -p[l[r]] or -proclist to list all [or just running] processes, -g[l[r]] or -grplist to list all [or just running] ProcCon groups, arg identifies the object to list or the list start point. The grpListFlags apply only to -gl (-grplist) and identify the data to list: -a all grp data (same as -b -i -m -p -t) -b lists grp base data: priority, affinity, schedule class, -i lists input/output (I/O) counters for the grp, -m lists memory related statistics for the grp, -p lists active, terminated, total process counters for the grp, and -t lists timing statistics for the grp.

Example: "ProcCon -n" to list all alias rules, -l is defaulted

Example: "ProcCon -gd name" to list the group definition for 'name'

Example: "ProcCon -l -ps name" to list process rules starting at 'name'

Example: "ProcCon -l -pl" to list processes, both running and not running

Example: "ProcCon -glr" to list running ProcCon groups

NOTE: The flag fields that are displayed in the lists are explained after the list. -l is the default verb for ProcCon so it can be omitted. When you use -pd or -gd the name argument is required. When the start point argument is omitted, the list starts at the top. When group list flags are omitted, the base data is shown.
===========================================================================

-a
The -a switch is used to add ProcCon data to the ProcCon database. This switch must be followed by an object switch to show what to add. The format is '-a[l[f]] -objname args' where... l, which is a suffix to the verb, says to list the data after the add. The letter f, which is a suffix, shows full-length names, and long names are not truncated. The -objname is the type of object to add to the ProcCon database: -n or -namerule to add a process name (alias) rule, -pd or -procdef to add a process definition rule, and -gd or -grpdef to add a Process Group Definition rule. Args define the content of the object that is being added.

Example: "ProcCon -al -n 1 P "cmd*" "ProcName" "rule description""

Example: "ProcCon -a -pd ProcName -g GroupName -f g"

NOTE: See Help for the various objects for the argument details. For -pd or -gd the "l" suffix lists the summary data after the add. For -n the "l" suffix lists the full Alias rules table after the add. Use the -r or -u (replace or update) instead if the rule already exists. To avoid Windows 2000 parsing of %-containing data, use the Interactive mode.
===========================================================================

-r
The -r switch is used to replace ProcCon data in the ProcCon database. This switch must be followed by an object switch to show what to replace. The format is '-r[l[f]] -objname args' where... l, which is a suffix to the verb, says to list the data after the replace f, which is a suffix, shows full-length names, and long names are not truncated. The -objname is the type of object to replace in the ProcCon database: -n or -namerule to replace a process name (alias) rule, -pd or -procdef to replace a process definition rule, and -gd or -grpdef to replace a process group definition rule. Args define the new contents of the object that is being replaced.

Example: "ProcCon -rl -n 1 P "cmd*" "ProcName" "rule description"

Example: "ProcCon -r -pd ProcName -g GroupName -f g"

NOTE: See Help for the various objects for the argument details. Replace replaces all the data in the rule with the data that is specified. For -pd or -gd, the "l" suffix lists the summary data after the replace. For -n, the "l" suffix lists the full Alias rules table after the replace. Use the -u switch (update) instead of -r to update selected fields. Use the -a switch (add) instead of -r if the rule does not yet exist. To avoid Windows 2000 parsing of %-containing data, use the Interactive mode.
===========================================================================

-u
The -u switch is used to update ProcCon data in the ProcCon database. This switch must be followed by an object switch to show what to update. The format is '-u[l[f]] -objname args' where... l, which is a suffix to the verb, says to list the data after the update f, which is a suffix, shows full-length names, and long names are not truncated. The -objname is the type of object to update in the ProcCon database: -pd or -procdef to update a process definition rule, and -gd or -grpdef to update a Process Group Definition rule. Args define the new contents of the object that is being updated.

Example: "ProcCon -u -pd ProcName -g GroupName -f g" updates group membership

Example: "ProcCon -u -gd GrpName -f p -p a" updates priority in the definition

NOTE: See Help for the various objects for the argument details. The "l" suffix lists the process or group summary data after the update. The update cannot be used to remove fields in a rule. Instead, use replace. Use the -r switch (replace) instead of -u to replace all data in the rule. Use the -a switch (add) instead of -u if the rule does not yet exist. To avoid Windows 2000 parsing of %-containing data, use the Interactive mode.

-d
The -d switch is used to delete ProcCon data from the ProcCon database. This switch must be followed by an object switch to show what to delete. The format is '-d[l[f]] -objname arg' where... l, which is a suffix to the verb, says to list the data after the delete f, which is a suffix, shows full-length names, and long names are not truncated. The -objname is the type of object to delete from the ProcCon database: -n or -namerule to delete a process name (alias) rule, -pd or -procdef to delete a process definition rule, and -gd or -grpdef to delete a Process Group Definition rule. Arg identifies the object to delete.

Example: "ProcCon -dl -n 1"

Example: "ProcCon -d -pd ProcName

NOTE: For -n, the argument is an index number, for the others it is the name. For -n, the "l" suffix lists the full Alias rules table after the delete. The "l" suffix is ignored for -pd and -gd because there is nothing to list.
===========================================================================

-s
The -s switch is used to swap two ProcCon Alias rules in the ProcCon database. This switch must be followed by an object switch to show what to swap. The format is '-s[l[f]] -n index' where... l, which is a suffix to the verb, says to list the data after the swap. The letter f, which is a suffix, shows full-length names, and long names are not truncated. Use -n or -namerule to swap Alias rules (the only item that can be swapped). Arg identifies the lower of the two rules to swap.

Example: "ProcCon -sl -n 1" which swaps rules 1 and 2

NOTE: Although only Alias rules can be swapped, the -n switch is still needed. The "l" suffix lists the full Alias rules table after the swap. Swapping is defined for alias rules because they are sequence dependent.
===========================================================================

-k
The -k switch is used to kill a ProcCon group or any Windows 2000 process. This switch must be followed by an object switch to show what to kill. The format is '-k -obj args' where... -obj is the type of object to kill: -p to kill a process, args are pid and can optionally create time, -g to kill a ProcCon process group, and arg is the group name.

Example: "ProcCon -k -p 708 125703157757656250"

Example: "ProcCon -k -g GroupName

NOTE: Pids are reused by Windows 2000, so killing a process by pid can kill the wrong process. It is recommended to use create time. Create times are displayed by the -pl command without the -t option. All the normal Windows 2000 warnings concerning the killing processes apply.
===========================================================================

-m
The -m switch or mediator is used to stop or to start the ProcCon mediator process. The format is '-m start|stop|restart' where... start attempts to start the mediator process, stop attempts to stop the mediator process, restart attempts to stop, and then start the mediator process.

Example: "ProcCon -m stop" to stop the mediator (if it is running)

Example: "ProcCon -m start" to start the mediator if it is not running

NOTE: Only one copy of the mediator can be running; a second start is unsuccessful. The Mediator must only be stopped to upgrade or reinstall it. Because the Mediator should always be running, it should be restarted as soon as possible after the desired updates are made. If the ProcCon service is stopped while the Mediator is stopped, all running group names can disappear (though they can continue to monitor and limit the processes that they contain, if any.)
===========================================================================

-*
The -* switch is used to insert a comment in a ProcCon command stream. It is primarily intended for use in ProcCon command files. The format is '-* comment text'.

Example: "ProcCon -* ...lots of comment text..."
===========================================================================

-i
The -i switch is used to enter ProcCon Interactive mode. In this mode you have a ProcCon prompt and you can enter commands as if you had been at the standard command prompt, except that:
  • The target computer only needs to be specified once.
  • A connection with the target computer is maintained.
The format is '-i' ..., and there are no arguments. The default is non-interactive, and ProcCon is invoked for each command.

Example: "ProcCon -i"

NOTE: The commands in the Interactive mode and command-line commands are the same. Do not include other ProcCon switches following -i. In Interactive mode, the target computer can be changed by means of the -c switch. Select a computer and Interactive mode with proccon -c name -i. To leave the Interactive mode, press ENTER with no command input.
===========================================================================

-f
The -f switch is used to specify an input file for ProcCon commands. The format is '-f file-name' where... file-name is the name of the command file to read. The default is: input commands come from the ProcCon command line only.

Example: "ProcCon -f d:\\dir1\\filename.txt"

NOTE: Use the full path and the file name, including the extension. Do not include other ProcCon switches that follow '-f name'. Each line in the file must be a single ProcCon command. Any ProcCon command may be in the file, except -f or -i.
===========================================================================

-x
The -x switch is used to invoke a ProcCon administrative command. The actual command is included immediately following the 'x'. The format is '-xc args' where... c is the administrative command and args are the commands's args: '-xd outfile' dumps the ProcCon database to the file 'outfile', '-xr infile' restores the ProcCon database from the file 'infile'

Example: "ProcCon -xd d:\\dir1\\dumpfile.txt" to dump ProcCon data.

Example: "ProcCon -xr d:\\dir1\\dumpfile.txt" to restore ProcCon data.

NOTE: Currently, the only administrative commands are dump and restore. Do not include other ProcCon switches following '-xc args'. Restore replaces the entire ProcCon database with data in the file, and all current data is destroyed. The backup file is suitable for input by means of the -f or -xr commands. Do not use the administrative commands without fully understanding them.
===========================================================================

-?
The -? switch is used to receive ProcCon Help. Following the -? switch is any number of ProcCon switches for which Help is wanted. The format is '-? [switch list]'.

Example: "ProcCon -? -?" for help about Help, which is this display.

Example: "ProcCon -? -a -n" for Help on add (-a) and Alias rules (-n)

NOTE: Unlike actual ProcCon commands, the switches after -? are in any order.
===========================================================================

-n
The -n switch or -namerule switch is used to select a ProcCon name (alias) rule. The name (alias) rules are used to assign an alias to a process. If there is no alias rule for a process, the name defaults to the image name. Operations that apply to alias rules are add, delete, replace, list, and swap. The format is '-n index [match-type match-string proc-name desc]' where index is the zero-relative numerical table index for this rule, and match-type indicates what type of match to perform: P to match on the image (program) name use to start the process, D to match on a sub-folder in the path used to start the process, A to match on any substring of the path used to start the process, and match-string is the string to match with the text selected by match-type.

The question mark (?) symbol can be used as a wild card to match a single character, the asterisk (*) symbol can be used at the end to match any number of trailing characters, and proc-name is the alias name to use when a match is successful. The following patterns may be included in the proc-name: P is replaced by the image name (without the 'exe' suffix), D is replaced by the matching sub-folder name (D matches only), H is used to hide the running process in process lists, and desc is an optional description of the rule.

Example: "ProcCon -a -n 0 P c* ProcC" all images starting with c are 'ProcC'

Example: "ProcCon -s -n 0" table entries 0 and 1 are swapped

Example: "ProcCon -dl -n 2" table entry 2 is deleted and the table is listed

NOTE: For replace or delete, the index indicates the rule in question. List the index indicates the start point of the list (0 default). For add, the new line is added before the index supplied. For swap, the index indicates the first line of the two to swap. Use quotes around parts of the definition containing spaces. To avoid Windows 2000 parsing of %-containing data, use the Interactive mode.
===========================================================================

-ps
The -ps switch or -procsummary switch is used to list ProcCon process data objects. The summary list is a table of definitions without variable text. The format is '-ps[f][o] [name]' where... f, which is a suffix, shows full-length names, and long names are not truncated. The letter (o), which is a suffix, limits the list to only the definition matching 'name'. "Name" is the name of the process definition where you can start the listing.

Example: "ProcCon -l -ps Proc1" starts the list with Proc1

Example: "ProcCon -ps" starts the list at the top, and all definitions are listed

NOTE: The management flags are explained at the end of the list. If the start name does not exist, the list starts at the name after the list.
===========================================================================

-gs
The -gs switch or -grpsummary switch is used to list ProcCon process group data objects. The summary list is a table of definitions without variable text. The format is '-gs[f][o] [name]' where... f, which is a suffix, shows full-length names, and long names are not truncated. The letter (o), which is a suffix, limits the list to only the definition matching 'name'. "Name" is the name of the group definition where you can start the listing.

Example: "ProcCon -l -gs Grp1" starts the list with Grp1

Example: "ProcCon -gs" starts list at the top, all definitions are listed

NOTE: The management flags are explained at the end of the list. If the start name does not exist, the list starts at the name after the list.
===========================================================================

-pl
The -pl or -proclist switch is used to list ProcCon processes. The list contains two categories of process names:
  • Names that are known to ProcCon because they are displayed in the process definitions.
  • Processes that are known to ProcCon because they are running.
The format is '-p[l[r][o][f]] [name [pid]] [-g grp] [-t]' where... r, which is a suffix, is used to limit the list to running processes. The letter (o), which is a suffix, limits the list to only processes matching 'name [pid]'. The letter (f), which is a suffix, shows full-length names, and long names are not truncated. "Name" is the process name where you can start the listing. Pid is the process ID in the name where listing starts. The -g grp switch further limits the list to processes in group 'grp'. The -t switch displays the create time in the familiar date and time format.

Example: "ProcCon -l -pl Proc1" starts the list with Proc1

Example: "ProcCon -l -plo Proc1" lists only the processes that are named "Proc1"

Example: "ProcCon -plr" starts a list at the top, and includes only the running processes

Example: "ProcCon -pl -g grp1" shows a list of the processes in grp1

NOTE: The displayed flags are explained at the end of the list. If the start name does not exist, the list starts at the name after the list. Although the "l" is optional, it must be included to use any of the suffixes. The displayed create time is in an internal format, unless you use -t. Use the internal format with kill (-k) to select the process to kill.
===========================================================================

-gl
The -gl or -grplist switch is used to list ProcCon process groups. The list contains three categories of group names:
  • Names that are known to ProcCon because they are displayed in group definitions.
  • Names that are known to ProcCon because they are displayed in process definitions.
  • Groups that are known to ProcCon because they are running.
The format is '-g[l[r][o][f]] [name] [flags]' where... r, which is a suffix, is used to limit the list to running groups. The letter (o), which is a suffix, limits the list to only the group matching 'name'. The letter (f), which is a suffix, shows full-length names, and long names are not truncated. "Name" is the name where listing starts. Flags identify what group data to list: -a all group data (same as -b -i -m -p -t), -b lists group base data: priority, affinity, sched class, -i lists I/O counters for the group, -m lists memory related statistics for the group, -p lists active, terminated, total process counters for the group, and -t lists the timing statistics for the group.

Example: "ProcCon -l -gl Grp1 -i" starts the list with Grp1, and lists only the I/O data.

Example: "ProcCon -l -glo Grp1 -i" lists only Grp1, and lists only the I/O data.

Example: "ProcCon -glr -b -p -m" starts the list at the top, and lists only the running groups, as well as the lists base, process, and memory data for the groups.

NOTE: The displayed flags are explained at the end of the list. If the start name does not exist, the list starts at the name after the list. Although the "l" is optional, it must be included to use any of the suffixes. When the group list flags are omitted, the base data is shown (-b is assumed).
===========================================================================

-pd
The -pd or -procdef switch is used to select a ProcCon process data object. Depending on the operation, this switch is followed by a name or full definition. Operations that apply to procdefs are add, delete, replace, and list. The format is '-pd name [def]' where... name is the name of the process definition to operate on, def is needed for add and replace to define the process definition and consists of a set of switches and values (in any order) as follows: '-f value' to define management flags, and 'value' is any combination of G, A, P, or W that can mean apply rules for group membership, affinity, priority, or working set.

For example, '-f GPA', '-a value' to define an affinity mask. The 'value' may be decimal or hex and is a bit mask with one bit for each proc, 0x03 is procs 0 and 1, and '-g grpname' to associate the process with the group named 'grpname'. The '-p value' defines a base priority. The 'value' is I, B, N, A, H, or R for idle, below normal, normal, above normal, high, realtime, or '-w low high' to define process low and high working set values. The '-d "text"' defines descriptive text associated with the definition.

Example: "ProcCon -a -pd P1 -f a -a 0x0f" affinity to procs 0 to 3 for process P1

Example: "ProcCon -r -pd Px -f pa -a 1 -p N" affinity to proc 0 priority normal

NOTE: The management flag determines if the value is applied or not. The working set values are in 1 KB units so a limit of 200 means 200 KB. You can supply a value and not use it by not setting the related flag. The descriptive text is used to comment or document the definition. There is no management flag associated with the descriptive text.
===========================================================================

-gd
The -gd or -grpdef switch is used to select a ProcCon process group data object. Depending on the operation, this switch is followed by a name or full group definition. Operations that apply to grpdefs are add, delete, replace, and list. The format is '-gd name [def]' where... name is the name of the group definition to operate on, def is needed for add and replace to define the group definition and consists of a set of switches and values (in any order) are as follows: '-f value' to define management flags, 'value' is any combination of A, P, S, W, T, U, M, N, C, B, Q, X, Y, or Z that set the following group limits:
  • A=affinity
  • P=priority
  • S=schedule class
  • W=working set
  • T=proc time
  • U=grp time
  • M=proc memory
  • N=grp memory
  • C=proc count
  • B=breakaway OK
  • Q=silent breakaway
  • X=die on unhandled exception (no message box)
  • Y=end group when empty, group statistics are lost when group ends
  • Z=log message when the group time limit is exceeded, otherwise fail all procs
NOTE: The letters B, Q, X, Y, and Z are flags only, they do not have values.
  • The '-a value' defines an affinity mask. The 'value' may be decimal or hex and is a bit mask with 1 bit for each proc, and 0x03 is procs 0 and 1.
  • The '-p value' defines a base priority. The 'value' is I, B, N, A, H, or R for idle, below normal, normal, above normal, high, or realtime.
  • The '-s value' defines a group scheduling class in the range of 0 to 9.
  • The '-w low high' defines group low and high working set values.
  • The '-c value' defines an active process count limit for the grp.
  • The '-t value' defines a time limit for each process in milliseconds.
  • The '-u value' defines a time limit for the group in milliseconds.
  • The '-m value' defines a memory limit for each process in K.
  • The '-n value' defines a memory limit for the group in K.
  • The '-d "text"' defines the descriptive text that is associated with the definition.

Example: "ProcCon -a -gd Grp1 -f a -a 0x0f" affinity to procs 0 to 3 for group Grp1

Example: "ProcCon -r -gd Grpx -f pa -a 1 -p N" affinity to proc 0 priority normal

NOTE: The management flag determines if the value is applied or not. All memory values are in 1 KB units so a memory limit of 200 means 200 KB. You may supply a value and not use it by not setting the related flag. The descriptive text is used to comment or document the definition. There is no management flag associated with the descriptive text.
===========================================================================

-v
The -v or -version switch is used to view or change the ProcCon version and parm data. For a list operation, both types of data are shown. For a replace operation, ProcCon parameters are replaced or updated. The format is '[-r] -v [new data]' where... new data applies only to a replace operation and is a pair of parameters.

Example: "ProcCon -v" to view the version and the current parameter settings

Example: "ProcCon -r -v 60 10000" to set the management interval to 60 seconds and the timeout interval to 10 seconds (10,000 milliseconds)

NOTE: The only two parameters that are currently defined are the management poll delay in seconds and the request timeout in milliseconds. Both are required when using -r to replace either value.
Modification Type:MinorLast Reviewed:1/27/2006
Keywords:kbinfo KB296258
©2004 Microsoft Corporation. All rights reserved.