home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: SysTools / SysTools.zip / nice5.zip / readme.txt < prev   
Text File  |  1998-12-25  |  10KB  |  263 lines
  1.  
  2.   NICE/2 by Sharon Dagan <idagan@il.ibm.com>
  3.  
  4.  
  5.   Still under construction...
  6.  
  7.   NICE/2 is a long term effort to provide end users with a set of tools to
  8.   better control their OS/2 systems. NICE/2 is still under development and
  9.   will have more features with time. 'NICEPM', the NICE/2 PM control center
  10.   will hopefully be added soon - I still have to iron out some bugs...
  11.  
  12.   Please report bugs and suggestions to idagan@il.ibm.com.
  13.   NICE/2 Homepage is: http://www.geocities.com/Nashville/6525/os2.html
  14.  
  15.       Important: I'm listening... if you have a suggestion that could make
  16.                  NICE/2 better, please share it with me. Thanks :-)
  17.  
  18.  
  19.   What is it?
  20.  
  21.   Have you ever started a long XCOPY command that ate too much CPU? Have you
  22.   ever wanted to make Netscape/2 more responsive? NICE/2 is here to rescue.
  23.   With NICE/2 you can dynamically change priority of many processes in OS/2.
  24.   As opposed to programs such as SPE that starts a process in a given
  25.   priority, NICE/2 enables you to change the priority of processes and threads
  26.   AFTER they have been started.
  27.  
  28.  
  29.   Installation
  30.  
  31.   Simply copy NICE.EXE and NICED.EXE to somewhere in your PATH, and copy
  32.   NICE.DLL, NICEDHK.DLL and NICEDMN.DLL to somewhere in your LIBPATH. A typical
  33.   place will be your utility directory.
  34.  
  35.  
  36.   How to use it?
  37.  
  38.   NICE/2 is divided into a 'client' program and a 'server' program. At any
  39.   time, you can start the NICE/2 server (NICED.EXE) (even if the process you
  40.   intend to alter is already started) by issuing the command:
  41.  
  42.       niced.exe -start
  43.  
  44.   (If you intend to use NICE/2 alot, place 'niced.exe -start' in your
  45.   STARTUP.CMD file - NICE/2 engine takes only a fraction of OS/2 resources).
  46.  
  47.   After a few seconds, NICED returns. If no error has occurred, NICED will
  48.   report nothing. If a error has occurred, NICED terminates and reports the
  49.   error (see the error codes at the end of this document). After NICED is
  50.   started, you can alter the priority of a given PID by using NICE/2 command
  51.   line or by using the Context Menu of the Task List Window.
  52.  
  53.  
  54.   Using the GUI
  55.  
  56.   Bring up the Task List Window (CTRL+ESC) and select a process. Bring up the
  57.   context menu - notice that NICE/2 added a new submenu called 'Priority'.
  58.   From this menu, select
  59.  
  60.       [+] Increase Priority
  61.       [+] Decrease Priority
  62.  
  63.       Use these two to increase or decrease the priority delta of a process
  64.       without changing the priority class - this will add +1 (or subtract) to
  65.       any thread withing the process. Lets say we have the following process
  66.       (niceps.exe output) (*):
  67.  
  68.           PID   PPID  THRDS  TYPE  COMMAND
  69.           653     19      4     3  D:\DEMO\BLAH.EXE
  70.           TID  CLASS  DELTA
  71.             1   IDLE     31
  72.             2    REG     24
  73.             3    REG     30
  74.             4    FGS      1
  75.  
  76.       After increasing the priority, it will look like this:
  77.  
  78.           PID   PPID  THRDS  TYPE  COMMAND
  79.           653     19      4     3  D:\DEMO\BLAH.EXE
  80.           TID  CLASS  DELTA
  81.             1   IDLE     31
  82.             2    REG     25
  83.             3    REG     31
  84.             4    FGS      2
  85.  
  86.  
  87.       Make Idle
  88.       Make Regualr
  89.       Make Server
  90.  
  91.       Use these options to set the priority of all threads within a process to
  92.       a given priority.
  93.  
  94.           Make Idle    | Low    = IDLE 0
  95.           Make Idle    | Medium = IDLE 15
  96.           Make Idle    | High   = IDLE 31
  97.  
  98.           Make Regular | Low    = REGULAR 0
  99.           Make Regular | Medium = REGULAR 15
  100.           Make Regular | High   = REGULAR 31
  101.  
  102.           Make Server  | Low    = FOREGROUND SERVER 0
  103.           Make Server  | Medium = FOREGROUND SERVER 15
  104.           Make Server  | High   = FOREGROUND SERVER 31
  105.  
  106.       so issuing 'Make Idle | Medium' on the above process (*) will result in:
  107.  
  108.           PID   PPID  THRDS  TYPE  COMMAND
  109.           653     19      4     3  D:\DEMO\BLAH.EXE
  110.           TID  CLASS  DELTA
  111.             1   IDLE     15
  112.             2   IDLE     15
  113.             3   IDLE     15
  114.             4   IDLE     15
  115.  
  116.  
  117.   Using Command Line
  118.  
  119.   Use the command line to better control priorities. Lets say we want to change
  120.   the priority of PID 71 and send it into the 'background'. From OS/2 command
  121.   line, simply issue:
  122.  
  123.       nice.exe -p 71 -c i -d 7
  124.  
  125.   This will alter the priority of process 71 to class IDLE with DELTA of 7.
  126.   Possible values for the CLASS switch '-c' are:
  127.  
  128.       NC = NO CHANGE priority class will not change
  129.       I  = IDLE priority
  130.       R  = REGULAR priority (most user processes are in this class)
  131.       F  = FOREGROUNDSERVER priority
  132.       TC = TIME CRITICAL priority (use with caution)
  133.  
  134.   Possible values for the DELTA switch '-d' are:
  135.  
  136.       -31 =< DELTA <= +31
  137.  
  138.       Important: To INCREASE or DECREASE the delta of a thread, use the
  139.                  NOCHANGE (NC) priority class. For example, to lower
  140.                  the priority delta of a process by 3, do this:
  141.  
  142.                  nice.exe -p 71 -c nc -d -3
  143.  
  144.  
  145.   How to change the priority of a single thread?
  146.  
  147.   NICE/2 gives you a fine control over priorities, down to the level of
  148.   altering the priority of a single thread within a process. When you
  149.   issue the NICE command, an optional switch '-t' controls the TID to
  150.   alter. If no TID is given, *ALL* the threads within the target process
  151.   are altered. If a TID is given, NICE will change the priority of that
  152.   thread *ONLY*.
  153.  
  154.       Important: NICE/2 can alter priorities of a single threads only if
  155.                  they are running within a PM process. To all other processes
  156.                  (VIO, FS and VDM), NICE/2 can only alter the priority of all
  157.                  the threads *TOGETHER*.
  158.  
  159.  
  160.   NICE/2 SDK
  161.  
  162.   NICE/2 now includes a C and REXX SDK. This SDK includes:
  163.  
  164.       NICE/2 Library, Header file and sample for C developers. The following
  165.       APIs are included (NicePS and NiceMyPID can be easily programmed without
  166.       NICE/2):
  167.  
  168.           * NiceStatus() - see if the NICE/2 engine is running
  169.           * NiceSetPriority( PID, TID, CLASS, DELTA ) - set priority
  170.  
  171.  
  172.       REXX DLL for NICE/2 (RXNICE.DLL) with the following functions (see the
  173.       provided SAMPLE1.CMD and SAMPLE2.CMD for more details):
  174.  
  175.           * RxNiceLoadFuncs() - load the functions
  176.           * RxNiceDropFuncs() - drop the functions
  177.           * RxNiceStatus() - see if NICE/2 engine is running
  178.           * RxNiceSetPriority( PID, TID, CLASS, DELTA ) - set priority
  179.           * RxNicePS( PID, 'STEM' ) - reports process information
  180.           * RxNiceMyPID() - get the current process PID
  181.  
  182.  
  183.   NICE/2 utilities:
  184.  
  185.       * Utility to report process and thread information - NICEPS.EXE:
  186.  
  187.           niceps.exe [-p PID]
  188.  
  189.           When used without switches, NICEPS reports process information
  190.           of all processes within the system. When used with the '-p' switch,
  191.           NICEPS reports process and thread information of the given PID.
  192.           Example of NICEPS output:
  193.  
  194.               (assuming 653 is Netscape's PID)
  195.  
  196.               niceps.exe -p 653
  197.  
  198.               PID   PPID  THRDS  TYPE  COMMAND
  199.               653     19      4     3  D:\NETSCAPE\PROGRAM\NETSCAPE.EXE
  200.               TID  CLASS  DELTA
  201.                 1    REG     30
  202.                 2    REG     24
  203.                 3    REG     30
  204.                 4    REG     30
  205.  
  206.  
  207.       * Utility to start a process in a given priority - NICEX.EXE:
  208.  
  209.           nicex.exe -c CLASS -d DELTA COMMAND [...]
  210.  
  211.           Use this utility to start a process in a given priority. For example,
  212.           to start a long XCOPY command in the lowest priority availabe, issue
  213.           the following command:
  214.  
  215.           nicexec.exe -c i -d 0 xcopy f:\* g:\ /s
  216.  
  217.           This will start 'xcopy f:\* g:\ /s' in priority IDLE 0.
  218.  
  219.  
  220.   Known limitations but Working As Designed:
  221.   (don't bother me with these)
  222.  
  223.   * The priority of detached processes cannot be altered.
  224.   * The priority of processes with PID < PID_OF_PMSHELL cannot be altered.
  225.     (PID_OF_PMSHELL can be obtained by: 'niceps | sort | grep PMSHELL' - the
  226.     lowset PID of the two is the one).
  227.   * Single thread operations can be applied to PM processes only.
  228.   * If you have selected more than one process in the Task List Window,
  229.     the priority menu will no appear.
  230.  
  231.  
  232.   Known limitations:
  233.  
  234.   * When a VDM is brought to the foreground, the priority changes back to
  235.     the default of that VDM (usualy R0) - I will address this in a future
  236.     release.
  237.   * Possible minor memory leak - if you think NICE/2 leaks (swapper growing,
  238.     system becomes slow etc) please contact me.
  239.  
  240.  
  241.   NICE and NICED return codes (not a complete list):
  242.  
  243.   rc =  0   NO_ERROR                  no error
  244.   rc = -1   ERR_USAGE                 check switches
  245.   rc = -2   ERR_INSTANCE              another niced.exe is already running
  246.   rc = -3   ERR_ENGINE_STARTED        NICED already running
  247.   rc = -4   ERR_ENGINE_STOPPED        NICED not running
  248.   rc = -5   ERR_WINSETHOOK            internal error - contact the author
  249.   rc = -6   ERR_NOT_PM_PROCESS        the '-t' (TID) switch was specified but
  250.                                       the PID given is not a PM process
  251.   rc = -7   ERR_HWND_NOT_FOUND        internal error - contact the author
  252.   rc = -8   ERR_TLW_STARTED           TLW egnine already running
  253.   rc = -9   ERR_TLW_STOPPED           TLW engine not running
  254.   rc = -10  ERR_WINSUBCLASSWINDOW     internal error - contact the author
  255.   rc = -11  ERR_TLW_HWND_NOT_FOUND    internal error - contact the author
  256.  
  257.   rc = 303  ERROR_INVALID_PROCID      invalid PID was given
  258.   rc = 304  ERROR_INVALID_PDELTA      the value of the '-d' switch is invalid
  259.   rc = 307  ERROR_INVALID_PCLASS      the value of the '-c' switch is invalid
  260.   rc = 309  ERROR_INVALID_THREADID    invalid TID was given
  261.  
  262.  
  263.