SO! internal documentation

                           ////////    ////////    //
                         //           //      //   //
                         //////////   //      //   //
                                 //   //      //
                          ////////     ////////    //

                         (c) 2009, 2010 by Igor V. Krassikov


    Fist, sorry for my English :)

    So... SO! is inspired by Carsten Wimmer's GO!. It isn't remake, but
in some details SO! is very similar to GO!.

   Like GO!, SO! is able to show a list of running processes. But this
   list can be sorted by names, pid, ppid or time.

   Like GO!, SO! is able to kill processes. But if DosKillProcess() call is
   not enough, and so! (or xf86sup) device driver was loaded, SO! will try use
   it for hard kill such process. And SO! can kill whole process tree (I think,
   that it is more correct way) - not only specified process, but at first
   all its children.

   Like GO!, SO! is able to kill all instances of a program.

   Like GO!, SO! is able to check whether a process is running or not

   Like GO!, SO! is able to switch to other processes

   Like GO!, SO! is able to query an application's type. Buf SO! return
   more info, and can search program file in PATH (or even use running
   process info for locating program file).

   Like GO!, SO! is able to show your machine's uptime since last boot.
   But SO! show not only uptime, but boot time also :)

   Like GO!, SO! is able to show info about your disks and, at least on my
   computer, SO! is more accurate, then GO!

   Unlike GO!, SO! is able to count instances of specified process, and
   wait for specified process is [not] exists.

   Unlike GO!, SO! is able to show Windows list.

   Unlike GO!, SO! is able to sleep for specified time.

   Unlike GO!, SO! is able to reboot your computer, and ever to power off.

   Unlike GO!, SO! is able to remove non-empty directories (strange feature,
   heh? :))

   Unlike GO!, SO! is able to calculate md5 checksum, split lagre files into
   small parts.

   I never used some GO! features, so, I don't implement them. But you can
   inform me, if these features are required for you.

  Usage:
  ~~~~~
   SO! is easy to use, you can get a detailed help when running it without any
   command-line parameters.

   Output is colored using ANSI, but if you use redirect, color output turn
   to BW :)
   If the first argument is comma (,), it removed from command line. So, you
   can write

   so, diskinfo

   to get information about your drives (yet another strange feature :))


  Command line
  ~~~~~~~~~~~~
  SO   command   [arguments]

  command   │  arguments     │  description
────────────┼────────────────┼─────────────────────────────────────────────────────
  doc       │                │ Write so.doc in the current directory and output
            │                │ this text to screen
────────────┼────────────────┼─────────────────────────────────────────────────────
  ver       │                │ Short info about SO! version
────────────┼────────────────┼─────────────────────────────────────────────────────
 -pl[iptnu] │ [mask]         │ Output process list. This list can be sorted by:
            │                │ i:  PID     p:  PPID     t:  CPU time
            │                │ n:  Name    u:  unsorted (by delault)
            │                │
            │                │ If mask is defined, so! will output those processes,
            │                │ which names are matches mask (path and extension are
            │                │ ignored; used standard pmatch pattern (*,?,[-] wild-
            │                │ cards)). The '*' automatically added at the end of
            │                │ mask, so, 'so -pl ftp' will find both ftp.exe and
            │                │ ftpd.exe
────────────┼────────────────┼─────────────────────────────────────────────────────
 -lpl[iptnu]│ [mask]         │ Same as -pl, but module names includes path
────────────┼────────────────┼─────────────────────────────────────────────────────
 proclist   │                │ Same as -plu
────────────┼────────────────┼─────────────────────────────────────────────────────
 -wl[f]     │                │ Output windows list (without entries which have pid
            │                | or hwnd equal to zero)
            │                │ If you use -wlf, full windows list (according to
            │                │ WinQuerySwitchList call) will be outputed.
────────────┼────────────────┼─────────────────────────────────────────────────────
 winlist    │                │ Same as -wl
────────────┼────────────────┼─────────────────────────────────────────────────────
 -j         │ process        │ Jump to a `process'. Is used to switch to another
            │                │ process. On the command line you may specify an .EXE
            │                │ name or a PID.
────────────┼────────────────┼─────────────────────────────────────────────────────
 jump       │ process        │ Same as  -j
────────────┼────────────────┼─────────────────────────────────────────────────────
 -nl        │                │ Jack Tan's NoList simulation - remove programs from
            │                │ both the OS/2 window list and the OS/2 Alt-Esc
            │                │ round-robin (see below)
────────────┼────────────────┼─────────────────────────────────────────────────────
 nolist     │                │ Same as  -nl
────────────┼────────────────┼─────────────────────────────────────────────────────
 -k[t]      │ proc [proc[..]]│ This closes a process(es), but only its first
            │                │ instance. It can be be specified either by its .EXE
            │                │ name or by its PID.
            │                │ -kt closes a process with all its descendants.
────────────┼────────────────┼─────────────────────────────────────────────────────
 -ka        │ proc [proc[..]]│ This closes all instances of a program which name
            │                │ you supplied on the command line.
────────────┼────────────────┼─────────────────────────────────────────────────────
 kill       │ proc [proc[..]]│ Same as -k
────────────┼────────────────┼─────────────────────────────────────────────────────
 killall    │ proc [proc[..]]│ Same as -ka
────────────┼────────────────┼─────────────────────────────────────────────────────
 -cp        │ process        │ The -cp command checks whether a specific process
            │                │ is running in the system or not. The following
            │                │ Errorlevels are returned: 0 - Process is not running.
            │                │                           1 - Process is running.
            │                │ This feature is useful for batch files to check if
            │                │ a program should be started or not.
────────────┼────────────────┼─────────────────────────────────────────────────────
 exist      │ process        │ Same as -cp
────────────┼────────────────┼─────────────────────────────────────────────────────
 wait       │ [~|!]process   │ Wait for `process' exists (or, if ~ or ! used, wait
            │                │ for NOT exist (check existence every 100ms)
────────────┼────────────────┼─────────────────────────────────────────────────────
 -cnt       │ process        │ Count instances of `process'. Returned Errorlevel
            │                │ is equal to counted value. If count > 255,
            │                │ errorlevel 255 is returned.
────────────┼────────────────┼─────────────────────────────────────────────────────
 count      │ process        │ Same as -cnt
────────────┼────────────────┼─────────────────────────────────────────────────────
 -at        │ module         │ This shows the info about an application, ie. if it
            │                │ is an OS/2 or DOS program etc.
            │                │ Supply an module name as argument. If such file is
            │                │ absent in a current directory, PATH used for locate
            │                │ the program file. If search is unsuccessfull, SO!
            │                │ will try use process list to locate module file.
            │                │ This feature is useful when you need to find
            │                │ the full name of a program file, which running using
            │                │ path.
────────────┼────────────────┼─────────────────────────────────────────────────────
 whatis     │ module         │ Same as -at
────────────┼────────────────┼─────────────────────────────────────────────────────
 -ut        │                │ This shows how long your machine is running since
            │                │ the last reboot and time of this last reboot.
────────────┼────────────────┼─────────────────────────────────────────────────────
 uptime     │                │ Same as -ut
────────────┼────────────────┼─────────────────────────────────────────────────────
 -df        │                │ This shows information about your drives (Drive,
            │                │ Label, Location (Local/Remote), FileSystem, Size,
            │                │ Free Space, Used Space in %.
────────────┼────────────────┼─────────────────────────────────────────────────────
 diskinfo   │                │ Same as -df
────────────┼────────────────┼─────────────────────────────────────────────────────
 reboot     │                │ Reboot your computer
────────────┼────────────────┼─────────────────────────────────────────────────────
 shutdown   │                │ Sutdown your computer and power off using APM.
            │                │ Sorry, not tested feature, may not work on some
            │                │ computers!!!
────────────┼────────────────┼─────────────────────────────────────────────────────
 sleep      │  ###[s|m|h|d]  │ Sleep for ### seconds (minutes, hours, days)
            │  date  time    │ of wait for specified time (see below)
            │                │ Multiple time parameters are allowed (e.g.,
            │                │ so sleep 1d 2h 3m 15s). You can omit any
            │                │ parameter(s), but you must use this order -
            │                │ d, h, m, s. So, "3h 12s" is valid value, but
            │                │ "12s 3h" isn't.
────────────┼────────────────┼─────────────────────────────────────────────────────
 -rd        │ dir [dir[..]]  │ Remove directory `dir', even if it is not empty
────────────┼────────────────┼─────────────────────────────────────────────────────
 rmdir      │ dir [dir[..]]  │ Same as -rd
────────────┼────────────────┼─────────────────────────────────────────────────────
 md5sum     │ file [file[..]]│ Calculate md5sum for file(s) in binary mode. Files
            │                │ more 2Gbytes are allowed. Wildcards are allowed.
────────────┼────────────────┼─────────────────────────────────────────────────────
 sha1sum    │ file [file[..]]│ Calculate sha1sum for file(s) in binary mode. Files
            │                │ more 2Gbytes are allowed. Wildcards are allowed.
────────────┼────────────────┼─────────────────────────────────────────────────────
 md5        │ string [..]    │ Calculate md5sum for string(s).
────────────┼────────────────┼─────────────────────────────────────────────────────
 sha1       │ string [..]    │ Calculate sha1sum for string(s).
────────────┼────────────────┼─────────────────────────────────────────────────────
 split      │ file size [dir]│ Split file into dir (current if omited). Size is
            │                │ ###[bkmg]. Files more 2G are allowed, max part <2G.
────────────┼────────────────┼─────────────────────────────────────────────────────
-du[S1[cs]] │ dir            │ Get directory `dir' statistics. `S' - do not include
            │                │ subdirectories; `1' - first level subdirectories
            │                │ info (files count and total size); `c' to order by
            │                │ count, `s' to order by size, otherwise - by name.
────────────┼────────────────┼─────────────────────────────────────────────────────
 sys        │                │ Write so.sys into current directory. Setup
            │                │ procedure is very simple: add string
            │                │ DEVICE=DRIVE:\PATH\SO.SYS
            │                │ into your config.sys. But if you already use
            │                │ xf86sup.sys driver, you may not to install SO!
            │                │ driver - SO! is able to use xf86sup.sys also.
────────────┼────────────────┼─────────────────────────────────────────────────────
 check      │                │ See below the table
────────────┼────────────────┼─────────────────────────────────────────────────────
 -ip        │                │ See below the table
────────────┼────────────────┼─────────────────────────────────────────────────────
 ipinfo     │                │ Same as -ip
────────────┼────────────────┼─────────────────────────────────────────────────────
 calc       │                │ Simple command-line calculator: see below the table
────────────┴────────────────┴─────────────────────────────────────────────────────

    sleep
    ~~~~~

    so sleep date time   wait for specified time.

    Date is grigorian :) date in one of formats: YYYY-MM-DD (ISO), DD.MM.YYYY,
MM/DD/YYYY or YYYYMMDD. You can omit year (assumed current year), or both year and
month (assumed current). You can also omit date completely (in this case in shortcut
mode (see below) time has slightly another meaning). If year is two-digit (e.g. 08),
2000 added :)

Timezones not supported! Use localtime only.

    Time is in format HH:MM:SS (24h format). You can omit SS or both MM and SS parts.
By default, omitted parts are zeros (12:20 is 12:20:00).

          shortcut mode
          ~~~~~~~~~~~~~

There is another (shortcut) mode. In this case what XX:YY or XX means depends on
date availability:

value     │                                 means
──────────┼───────────────────────────────────┼──────────────────────────────────────
          │         Date is specified         │          Date is absent
──────────┼───────────────────────────────────┼──────────────────────────────────────
XX:YY:ZZ  │ XX hours, YY minutes, ZZ seconds  │XX hours, YY minutes, ZZ seconds
──────────┼───────────────────────────────────┼──────────────────────────────────────
XX:YY     │ XX hours, YY minutes, 00 seconds  │XX minutes, YY seconds of current hour
──────────┼───────────────────────────────────┼──────────────────────────────────────
XX        │ XX hours, 00 minutes, 00 seconds  │XX seconds of current hour and minute

If destination time is in past while date is absent, program attempt to add some time
to destination - one minute, if XX specified; one hour, if XX:YY specified, and one day
in case of XX:YY:ZZ. For example, if now is November 8, 2009, 09:34:15:

command line       │           wait for
───────────────────┼───────────────────────────────────────────────
so sleep  25       │  2009-11-08  09:34:25
so sleep  5        │  2009-11-08  09:35:05
so sleep  33:25    │  2009-11-08  10:33:25
so sleep  09:33:25 │  2009-11-09  09:33:25
so sleep  10:33:25 │  2009-11-08  10:33:25

This feature is intend for simplified input if you needs waiting for a little time.

You can switch between modes using command

so sleep switch

Current mode saved in OS2.INI file, so, don't forget to switch in new system :)

    nolist
    ~~~~~~
   nolist removes and restores programs in the OS/2 window list and the
Alt-Esc round-robin.  OS/2 text (VIO), Presentation Manager, DOS, and
WIN-OS/2 programs are supported.  Each program is specified by a unique
identifier (ID).  Each ID can be either the mask of the process name
(standard `pmatch' algorithm, allows *, ? and [-] wildcards, case-sensitive)
or the system process ID.  Process IDs are assumed to be decimal.
Either '-' or '/' can be used as the switch prefix; supported switches are
(case-insensitive):

         /A         Use both /A:J and /A:V switches
            /A:J    Add processes to the Alt-Esc round-robin (jumpable)
            /A:V    Add processes to the window list (visible)
         /L         List process IDs (same as `so -wl')
         /M         Apply to each entry if there are multiple matches (default !)
         /S         Apply to first entry if there are multiple matches
         /R         Use both /R:J and /R:V switches (default action)
            /R:J    Remove processes from the Alt-Esc round-robin (nonjumpable)
            /R:V    Remove processes from the window list (invisible)

Full command-line pattern is

so -nl opt [opt ... ] ID [ID ...] [opt [opt ... ] ID [ID ...] ...]

For example,

so -nl -r:j -m Help* -s -a FC* -l

means:
    remove all programs with first letters of title 'Help' from the Alt-Esc
round-robin, restore first program with first letters of title 'FC' in the
OS/2 window list and the Alt-Esc round-robin, and show resulting windows list.

    Note: unlike NoList:
    - hex ID not supported
    - wildcards are supported
    - apply to multiple entries id default behaviour.

P.S. This feature was added by request of Vadim "Oxyd" Priluzkiy, FidoNet 2:466/466.152

    check
    ~~~~~

    There is an advanced check feature in SO!. You can use it mainly in batch files
to check whether some (complex) condition is true or false. For example, you can
check free space on disk C: using following code:

so check diskfree C: more 500M return 2 otherwise 4

This line tell SO!, that it must return errorlevel 2, if free space on drive C: more
than 500 Megabytes, or 4 otherwise.

Command line must follow this pattern:

so check  expression  [return okcode [otherwise failcode]]

where `okcode' and `failcode' are the errorlevels, which SO! will return if expression
is true (okcode, 1 by default) or false (failcode, 0 by default). If there is an error
(e.g., syntax error) in expression, SO! return errorlevel 255.

expression can be:

1. OR'ed other expressions    ( expr1 or  expr2 )     lowest  priority
2. AND'ed other expressions   ( expr1 and expr2 )     highest priority
3. NOT'ed expression          ( not expr )
4. expression in parenthesis  (  (expr)  )
5. Comparing of two values    (  val1  comp   val2  )
   where `comp' can be one of:
                         less
                         more   (you can use `greater')
                         equal
                         not less
                         not more
                         not equal
    If there is quotes around main expression, you can use natural operators
    <, <=, >, >=, <>, = (< and > symbols have special meanings in command lines).

    5.1. Value is an integer number or integer value, returned by "functions".
         Integer number is any integer with optional suffix (K, M or G), e.g.
         256, 145K (145*1024), 12M (12*1024*1024), 2G (2*1024*1024*1024).
         Non-integer values not allowed!

    5.2. "Functions" are:
         disksize d:        returns size of drive d: in bytes; in case of
                            error (incorrect drive etc) returns 0.
         diskfree d:        returns free spaxe on drive d: in bytes; in case
                            of error (incorrect drive etc) returns 0.
         filesize file      returns size of `file'. If this file not exist,
                            returns -1!!!
         dirsize  dir       returns total size of all files in directory `dir'
                            and subdirectories. If directory not exist,
                            return 0.
         proc module count  returns count instances of process `module'.
         count proc module  The same as "proc module count".

    5.3. You can use arithmetic operators  `add', `sub', `mul', and `div' with
         integer values. These operators corresponding to usually +, -, * and /
         arithmetic operators with their priorities. All operations are integer
         (e.g., 7 div 2 == 3).

6. "Boolean functions"
    file filename exist       returns true, if file `filename' is exist, false
                              otherwise
    file filename not exist   returns true, if file `filename' is not exist,
                              false otherwise
    proc module exist         returns true, if process `module' is running,
                              false otherwise
    proc module not exist     returns true, if process `module' is not running,
                              false otherwise

All keywords

    add        div      filesize   no
    and        equal    greater    not
    count      exist    less       proc
    diskfree   exists   more       process
    disksize   file     mul        sub

are case-sensitive! Please, don't forget this! Also, keywords `not' and `no'
(also `exists' and `exist', `proc' and `process') are absolutely equivalent.

If some parameter (such as file name or process name) is equal to some keyword,
you'll get syntax error. The solution is to put such word in brackets (which are
ignored during parse), for example

so check file [not] exist

checks existence of file "not". You can also use brackets for names, which are not
keywords. Sorry, but spaces not allowed in the names of files and processes...

Some examples:

If size of disk E: more than twice free space on disk D: return 1, otherwise 0:
so check disksize E: more diskfree D: mul 2

If process "make" exist and either size of file "c:\flag1" less than 2K or size
of file "c:\flag2" more than 3K, return 5, otherwise 8:
so check proc [make] exist and (filesize [c:\flag1] less 2K or filesize [c:\flag2] more 3K) return 5 otherwise 8

If process "make" has more 20 instances and free space on drive E: less than 10M, return 2,
otherwise return 0:
so check count proc [make] more 20 and diskfree E: less 10M return 2

    ipinfo
    ~~~~~~

You can use SO! as small IP-calculator :) to obtain info about ip addresses and netmasks
(it is too exhausting to juggle with bits :-))

SO! take IP address and netmask in three forms:

so ipinfo ###.###.###.###/##                       (address, netmask bits)
so ipinfo ###.###.###.###  ###.###.###.###         (address, netmask)
so ipinfo ###.###.###.### - ###.###.###.###        (min - max ip address of subnet)

Please, note spaces around dash - in fact, 4 arguments are passed to SO! in this case.
For example, results of calls

so ipinfo 194.44.31.225/28
so ipinfo 194.44.31.225 255.255.255.240
so ipinfo 194.44.31.225 - 194.44.31.238

will be the same. Notice that if you use last form, SO! evaluate minimal subnet which include
both specified addresses. For example, what is minimal subnet, which include 194.44.31.225
and 194.44.31.228? Command "so ipinfo 194.44.31.225 - 194.44.31.228" returns:

IP address      194  .    44  .    31  .   225  / 29     194.44.31.225/29
IP bits      11000010.00101100.00011111.11100001
Mask bytes      255  .   255  .   255  .   248  / 29     255.255.255.248
Mask bits    11111111.11111111.11111111.11111000
Network         194  .    44  .    31  .   224           194.44.31.224
Broadcast       194  .    44  .    31  .   231           194.44.31.231
First host      194  .    44  .    31  .   225           194.44.31.225
Last host       194  .    44  .    31  .   230           194.44.31.230
Total hosts     6

    calc
    ~~~~
You can use SO! as simple command-line calculator: "so calc expression"
SO! evaluate expression and display result.

You can use standard arithmetic operations, such as + - * / ** (involution),
and use parenthesis. Raise to power is right-associative (a**b**c == a**(b**c)).

List of accessible built-in functions:
sin, cos, tan (or tg), log (or ln), exp, lg (== log10), sqrt.

Constants pi and e are also allowed:
so calc sin(pi/2)   == 1

You can (permanently) change display precision using
so precision ##     or    so digits ##     command. By default ## == 6.

If expression is omitted, SO! puts in multiline calculator mode: you can input
single expression per line, and it will be evaluated. You can use variables - any word,
beginning from letter and containing letters and digits, is variable name (of course,
exclude keywords, such as function's name or constant). All variables initially set to 0.0.
To assign value to variable use standard symbol '='. After

var = 2 + 4

variable 'var' will contain value 6. To list all variables use command 'varlist', to remove
all variables - use 'clean'. To quit from calculator - quit, exit or bye.

For example, small calc session:

user input                 output
----------------------------------------
so calc
2+sin(pi/2)
                           Result is: 3
b = c = cos(e)
                           Result is: -0.911734
varlist
                           b =  -0.911734
                           c =  -0.911734
precision 12
                           New digits: 12
varlist
                           b =  -0.911733914787
                           c =  -0.911733914787
clean
d = sqrt(3*3+4*4)
                           Result is: 5
varlist
                           d = 5
quit





SO.SYS API:
~~~~~~~~~~

    Device name: /DEV/SO!$
    When device is opened, you can use DosDevIOCtl call:

    Category:      160
    Function:      160
    Param:         PID of the process being killed (USHORT)
    Return:        Error code (USHORT)

    Category:      160
    Function:      161
    Param:         No param
    Return:        USHORT driver version: lsb - minor version, msb - major version.


Like GO!:

  Legal Disclaimer:
  ~~~~~~~~~~~~~~~~
   Permission is granted to any individual or institution to use, copy, or
   redistribute this executable as long as it is not modified and that it
   is not sold for profit.

   SO! and its associated utilities are provided AS IS and come with no
   warranty of any kind, either expressed or implied. In no event will
   the copyright holder be liable for any damages resulting from the use
   of this software.

  Registration:
  ~~~~~~~~~~~~
   SO! is neither Freeware nor Shareware.  It's Cardware.  If you use SO!
   on a regular basis and like it, you have to send a picture postcard
   from your location to the author.  His snail mail address is shown below.

   Any help in documentation writing and correcting mistakes in English
   kindly accepted!

  Final Note:
  ~~~~~~~~~~
   If you want to contact me, write to kiyanyn@gmail.com

   Comments, Bug-Reports and Feature-Requests are welcome.  Flames are not.

   Send any nice picture postcards to:

        Igor V. Krassikov
        IPMS, dep.44
        Krzhyzhanovsky str., 3
        03142  Kiev
        Ukraine