═══ 1. Function and Command Line Syntax ═══

Version 2, August 1994 
This version has the ability to "switch focus to self", meaning that it can 
switch focus to that session that is invoking it.  This is useful when running 
REXX programs in several sessions such as with the author's RXMP package 
(RXMSGBOX pop-up message), and focus will be switched more than once.  Using a 
single asterisk as the operand to PMSW or PMSW2 is a request to switch to self. 

The PMSW application is presented in two forms: 

o PMSW.EXE 

o PMSW2.DLL 

PMSW* is invoked with two arguments: 

 1. Name mask of task in switch list 

 2. Optional "/r" switch to suppress actual focus change 

If the string passed as the first argument matches a name in the WorkPlace 
Shell "Switch List" that is made the focus with the Ctrl+Esc keys, then that 
task is given the focus with a call to WinSwitchToProgram.  The name mask may 
contain - usually does contain - wild card characters.  These characters are 
the asterisk and question mark, and they have their usual DOS command line 
meanings. 

o * wild card matches zero or more characters 

o ? wild card matches exactly one character 

Version 2:  if the first operand is an asterisk, then the second operand is 
ignored, and focus will switch to this session that invoked PMSW.  Return codes 
with this request are only:  0/FOCUS: or 2/ERROR: and no test return without 
focus switch can be done. 

Mask=*ABC*
This mask matches a name containing the letters ABC. 

Mask=*A*B*C*
This mask matches a name containing the letters A, B, C, but not necessarily 
next to each other. 


═══ 2. Sample Application ═══

The PMSW application is used in OS/2 .CMD files that are batch command files or 
REXX programs.  The .CMD file can invoke PMSW to test if a named task is 
already active and to switch focus to that task, or it can launch a task and 
change focus to that task once that task is available.  The REXX can contain 
logic such that, if the target DOS application is already active when the REXX 
begins, the DOS application receives the focus instead of the REXX starting 
another DOS application window.  This is important to PC LAN administrators who 
want to place central applications on the LAN but who need to provide OS/2 
users with the tools to automatically acquire LAN connection to the 
application, tailoring the DOS startup parameters for the target application so 
that its environment, PATH, etc. are properly initialized. 

At a customer site, the CCMAIL application resides on the LAN.  A MAIL program 
folder can be defined on the desktop that invokes the MAIL.CMD REXX program. 
This program tests to see if the target CCMAIL application is now active, and 
switches focus to it if so.  If the CCMAIL application is not active, then 
MAIL.CMD REXX checks to see if the user is now logged onto the LAN (a LOGON 
command has been done), and if the CCMAIL LAN drive has been connected before 
issuing a START command for CCMAIL and switching focus to it. 


═══ 2.1. Sample MAIL.CMD for PMSW Program Call ═══

/* REXX MAIL.CMD Uses PMSW.EXE program calls */
'SETLOCAL'
'C:'
'CD \CCMAIL'
if 0 < RxFuncQuery('SysLoadFuncs') then
   do
      Call rxfuncadd 'SysLoadFuncs','REXXUTIL','SysLoadFuncs'
      Call SysLoadFuncs
   end
CCMAIL='CCMAIL';
FirstName=""; LastName=""; ProcOpts=""; UserPassWord="";
parse upper arg FirstName LastName UserPassWord;
CCMAILServer='ccmail';
MDRIVE.0=0;
RC.0='FOCUS:'; RC.1='READY:'; RC.2='ERROR:';
irc=SysFileTree('M:\CCMAIL\MAIL.*','MDRIVE','FSO');
if MDRIVE.0<1 then
   do
      '@NET USE M: ' CCMAILServer;
      RRC=RC;
   end
else RRC=0

IF RRC=0 then
   do
   bREADY=0;
   'PMSW' ccmail '/R';
   Result=RC.RC
   if Result\='READY:' then
      'START "CCMAIL" /C /MIN /WIN c:\CCMAIL\CCMAIL.BAT' FirstName LastName UserPassword;
   else
      do
         'PMSW' ccmail; Result=RC.RC;
         if Result='FOCUS:' then bREADY=1;
      end;
   do while (bREADY<1);
      'PMSW' ccmail '/R'
      Result=RC.RC;
      if Result='READY:' then
         do
            'PMSW' ccmail
            Result=RC.RC;
            if Result='FOCUS:' then
               bREADY=1;
         end;
      else Call SysSleep(2);
   end;
END;
else
   do
      if RRC=2 then
         'net use m: /d';
      say "UNABLE TO ACCESS CCMAIL"
   end;
byby:;
'@EXIT';


═══ 2.2. Sample MAIL.CMD for PMSW2 REXX Function ═══

/* REXX MAIL.CMD */
'SETLOCAL'
'C:'
'CD \CCMAIL'
if 0 < RxFuncQuery('SysLoadFuncs') THEN DO;
   Call rxfuncadd 'SysLoadFuncs','REXXUTIL','SysLoadFuncs';
   Call SysLoadFuncs;
END;
CCMAIL='CCMAIL';
RC=RXFUNCADD('PMSW2','PMSW2','PMSW2');
FirstName=""; LastName=""; ProcOpts=""; UserPassWord="";
parse upper arg FirstName LastName UserPassWord;
CCMAILServer='ccmail';
MDRIVE.0=0;
irc=SysFileTree('M:\CCMAIL\MAIL.*','MDRIVE','FSO');
if MDRIVE.0<1 then do;
   '@NET USE M: ' CCMAILServer;
   RRC=RC;
end;
else do;
  RRC=0;
end;
IF RRC=0 THEN DO; bREADY=0;
   Result=PMSW2(ccmail,'/r');
   if Result\='READY:' then do;
      'START "CCMAIL" /C /MIN /WIN c:\CCMAIL\CCMAIL.BAT' FirstName LastName UserPassword;
   end;
   else do;
      Result=PMSW2(ccmail); if Result='FOCUS:' then bREADY=1;
   end;
   do while (bREADY<1);
      Result=PMSW2(ccmail,'/r');
      if Result='READY:' then do;
         Result=PMSW2(ccmail);
         if Result='FOCUS:' then do;
            bREADY=1;
         end;
      end;
      else Call SysSleep(2);
   end;
END;
else do;
   if RRC=2 then do;
      'net use m: /d';
   end;
   say "UNABLE TO ACCESS CCMAIL"
end;
byby:;
RC=RXFUNCDROP('PMSW2');
'@EXIT';


═══ 2.3. Sample CCMAIL.BAT DOS Batch File ═══

@ECHO OFF
C:
CD \CCMAIL
CD M:\CCMAIL
SET CCCONFIG=C:\CCMAIL\CCMAIL.INI
SET PATH=M:\CCMAIL;%PATH%
SET TEMP=C:\
SET WP=/D-C:\WP51/PF-C:\WP51/M-VIEW
IF X==X%1 GOTO NONAME
IF X==X%3 GOTO NOPASS
M:MAIL /N"%1 %2" /P"%3"
GOTO EXIT
:NOPASS
M:MAIL /N"%1 %2"
GOTO EXIT
:NONAME
M:MAIL
:EXIT
EXIT


═══ 3. Technical Details ═══

Processing outline: 

 1. PMSW2 is defined as a Rexx function handler .DLL, and PMSW as an OS/2 .EXE 
    program 

 2. PMSW/PMSW2 examines the input parameters to see if there is a task name and 
    optional /r flag. 

 3. It requests a count of items in the switch list using WinQuerySwitchList. 

 4. It allocates memory to hold the full switch list array. 

 5. It requests return of items in the switch list using WinQuerySwitchList. 

 6. It scans the entries in the switch list array and matches the name mask 
    given against each item. 

 7. The MSKCHK function supports use of multiple "*" and "?" wild cards with 
    the usual meanings 

 8. On finding a name match, if the /r switch was used, the REXX return string 
    value is set to READY:, else the REXX return string value is set to FOCUS:. 
    PMSW returns values 1 and 0 instead. 

 9. If FOCUS:, then call WinSwitchToProgram using the switch list entry handle 
    in the SWCNTRL structure of the matching switch list entry. 

10. RETURN from PMSW2 to the REXX program that invoked it, or return from 
    PMSW.EXE to the .CMD file or other caller. 

Note that return is immediate, regardless of change in focus.  The calling .CMD 
continues execution while the user sees the focus change to the target task. To 
the person at the keyboard, it appears as though the .CMD window, if visible, 
has been replaced by the target application window, which now has the keyboard 
focus. 


═══ 3.1. MSKCHK Function ═══

This function is a handy piece of code developed from the author's IBM 370 
assembler code (that form of the code is available on Compuserve in the 
consultants' forum).  The function can match a mask string which contains 
multiple wild cards equivalent to "*" and "?" (the wild card characters can be 
specified, to avoid problems with strings that contain "*" and "?"). 

The arguments passed to MSKCHK are: 

o Ptr to mask string 

o Length of mask string (hold-over from non-ASCIIZ assembler, and also supports 
  mask containing nulls, by the way) 

o Ptr to area to scan 

o Length of area to scan 

o Ptr to "?" substitute character 

o Ptr to "*" substitute character 

The code now skips leading and trailing blanks in the area to scan, but a block 
of code could be selectively suppressed to permit using leading and trailing 
blanks in both mask string and in area to scan, if appropriate.  The code could 
also accept another substitute character that would be the character to remove 
if leading or trailing in the area to scan, with the default stripped character 
being the blank. 

To ignore case in letters scanned, it's best to translate both mask and area to 
the same case prior to calling MSKCHK, as this is more efficient than 
translating characters as the scan proceeds, unless you choose to use in-line 
macro expansion code to do the single character translation.  Without altering 
the code in MSKCHK, you could still support case-insensitive national language 
support (NLS) translation by doing a translation prior to invoking MSKCHK. It 
is usually not sufficient to add a constant to a character value to translate 
from lower to upper or the reverse, when NLS translation must be done. 

The use of multiple wild card characters in MSKCHK means that it provides 
powerful pattern recognition function.  An appropriate mask can detect the 
presence of two or more "floating" substrings within scanned data. The mask 
value of "*ABC*DEF*" will detect if an area contains both of the 3-letter 
strings and "ABC" precedes "DEF". 

A mask string can be longer than the area scanned, as long as the total length 
of constant characters and "?" characters is less than or equal to the length 
of the area to scan. 

MSKCHK returns 0 for match and 8 for non-match. 


═══ 4. Author & Legal Stuff ═══


═══ 4.1. Copyright ═══

Copyright (C) 1993,1994 by Bruce E. HФgman. All Rights Reserved. 

License to use: 

PMSW and PMSW2 may be used by any person, corporation, or government agency 
without cost.  PMSW and PMSW2 may be distributed by any computer bulletin board 
service (BBS), including but not limited to Compuserve, BIX, and Prodigy, 
provided that no fees are charged for this distribution other than usual and 
customary line or session connect charges, or charges usual and customary for 
shipping and handling of magnetic media and documentation. 

Specific permission is granted International Business Machines Corporation 
(IBM) to distribute this software, including C and REXX source programs as 
sample programs in any IBM product. 


═══ 4.2. Author ═══

PMSW and PMSW2 were developed originally for the US Dept of Energy, Energy 
Information Administration (EIA), Washington DC by Bruce E. HФgman of 
Electronic Data Systems Corporation (EDS).  The author can be reached via 
Compuserve 72050,1327 or at the mailing address: 1338 Avocado Isle, Fort 
Lauderdale FL 33315-1344. 

The author was an instructor in computer sciences while on active duty with the 
Air Force during the Vietnam years, and has been programming since 1965 on 
every type of weird iron, stranger operating systems, and most popular and 
arcane programming languages.  He's proudest of having taught US Marines at 
Quantico Virginia. 


═══ 4.3. Warranty ═══

This software is provided without warranty as a public service by the author. 
Neither the author, nor the federal government or EDS Corporation makes any 
guarantee as to the usefulness of this software or its correct operation. 


═══ <hidden>  ═══

The "*" means zero or more characters in this position, and "?" means exactly 
one character in this