home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1993 #2 / Image.iso / os2 / pmsw2.zip / CSOURCE / PMSW2 / PMSW2.IPF < prev    next >
Text File  |  1993-04-20  |  6KB  |  133 lines
  1. :userdoc.
  2. :docprof.
  3. :title.PMSW2 - Switch Focus to Application by Name
  4. :h1 group=1.Function and Command Line Syntax
  5. :link reftype=hd refid=EIAOS2 auto titlebar=none scroll=none rules=none vpx=0% vpy=0% vpcx=100% vpcy=100%.
  6. PMSW2 is used in REXX programs to switch desktop focus to an
  7. application whose name appears in the DESKTOP switch list.
  8. :p.PMSW2
  9. is called as a REXX function with two arguments:
  10. :ol.
  11. :li.Name mask of task in switch list
  12. :li.Optional "/r" switch to suppress actual focus change
  13. :eol.
  14. :p.If the string passed as the first argument matches a name in
  15. the WorkPlace Shell "Switch List" that is made the focus
  16. with the Ctrl+Esc keys, then that task is given the focus with
  17. a call to WinSwitchToProgram.  The name mask may contain -
  18. usually does contain - wild card characters.  These characters are
  19. the asterisk and question mark, and they have their usual
  20. DOS command line meanings.
  21. :ul.
  22. :li.* wild card matches zero or more characters
  23. :li.? wild card matches exactly one character
  24. :eul.
  25. :xmp.Mask=*ABC*:exmp.
  26. This mask matches a name containing the letters ABC.
  27. :xmp.Mask=*A*B*C*:exmp.
  28. This mask matches a name containing the letters A, B, C, but not
  29. necessarily next to each other.
  30. :h1.Sample Application
  31. :p.PMSW2 can be used to launch a DOS
  32. program from an OS/2 REXX and switch control to it.
  33. The REXX can contain logic such that, if the target DOS
  34. application is already active when the REXX begins,
  35. the DOS application receives the focus instead of the
  36. REXX starting another DOS application window.
  37. This is important to PC LAN administrators who want to
  38. place central applications on the LAN but who need to
  39. provide OS/2 users with the tools to automatically
  40. acquire LAN connection to the application, tailoring the
  41. DOS startup parameters for the target application so that
  42. its environment, PATH, etc. are properly initialized.
  43. :p.At the author's customer's site, the CCMAIL application resides on
  44. the LAN.  A MAIL program folder can be defined on the desktop that
  45. invokes the MAIL.CMD REXX program.  This program tests to see if the
  46. target CCMAIL application is now active, and switches focus to it if so.
  47. If the CCMAIL application is not active, then MAIL.CMD REXX checks to
  48. see if the user is now logged onto the LAN (a LOGON command has been
  49. done), and if the CCMAIL LAN drive has been connected before issuing a
  50. START command for CCMAIL and switching focus to it.
  51. :p.The logic for starting a DOS application:
  52. :cgraphic.
  53. RESULT=PMSW2('*APPNAMESTRING*','/R');
  54. IF RESULT='READY&colon.' THEN DO;
  55.    RESULT=PMSW2('*APPNAMESTRING*');
  56.    IF RESULT='FOCUS&colon.' THEN EXIT;
  57.    SAY 'COULD NOT SWITCH FOCUS'
  58.    EXIT;
  59. END;
  60. 'START "APPNAMESTRING" /C /MIN DOSAPP.EXE'
  61. /* OR START A REXX TO DEFINE A DOS OBJECT WITH OPEN=PROGRAM */
  62. BSUCCESS=0;
  63. DO WHILE BSUCCESS<1;
  64.    RESULT=PMSW2('*APPNAMESTRING*','/R');
  65.    IF RESULT='READY&colon.' THEN BSUCCESS=1;
  66.    ELSE CALL SYSSLEEP(2); /* WAIT FOR 2 SECONDS OR SO */
  67.    /* PUT A LIMIT ON CALLS HERE */
  68. END;
  69. :ecgraphic.
  70. :h1 id=TechData.Technical Details
  71. :p.Processing outline:
  72. :ol.
  73. :li.PMSW2 is defined as a Rexx function handler
  74. :li.It examines the input parameters to see if there is a task name
  75. and optional /r flag.
  76. :li.It requests a count of items in the switch list
  77. using WinQuerySwitchList.
  78. :li.It allocates memory to hold the full switch list array.
  79. :li.It requests return of items in the switch list using
  80. WinQuerySwitchList.
  81. :li.It scans the entries in the switch list array and matches the
  82. name mask given against each item.
  83. :li.The MSKCHK function supports use of multiple "*" and "?" wild cards
  84. with the usual:link reftype=fn refid=wild. meanings :elink.
  85. :fn id=wild.The "*" means zero or more characters in this position,
  86. and "?" means exactly one character in this position.:efn.
  87. :li.On finding a name match, if the /r switch was used,
  88. the REXX return string value is set to READY&colon., else
  89. the REXX return string value is set to FOCUS&colon..
  90. :li.If FOCUS&colon., then call WinSwitchToProgram using the
  91. switch list entry handle in the SWCNTRL structure
  92. of the matching switch list entry.
  93. :li.RETURN from PMSW2 to the REXX program that invoked it.
  94. :eol.
  95. :p.Note that return is immediate, regardless of change in focus.
  96. The calling REXX program continues execution while the
  97. user sees the focus change to the target task.
  98. To the person at the keyboard, it appears as though the
  99. REXX program window, if visible, has been replaced by the
  100. target application window, which now has the keyboard focus.
  101. :h1 group=11.Author &. Legal Stuff
  102. :h2 group=12 titlebar=yes scroll=vertical rules=none id=Cpyr.Copyright
  103. :hp9.Copyright (C) 1993 by Bruce E. Högman.:ehp9.:hp8. All Rights Reserved.:ehp8.
  104. PMSW2 may be used by any person, corporation, or government agency
  105. without cost.  PMSW2 may be distributed by any computer bulletin board
  106. service (BBS), including but not limited to Compuserve, BIX, and
  107. Prodigy, provided that no fees are charged for this distribution other
  108. than usual and customary line or session connect charges, or charges
  109. usual and customary for shipping and handling of magnetic media and
  110. documentation.
  111. :h2 group=13 titlebar=yes scroll=vertical rules=none id=Auth.Author
  112. PMSW2 was developed for the US Dept of Energy, Energy Information
  113. Administration (EIA), Forrestal Bldg. MailStop EI-10, 1000 Independence
  114. Ave.  S.W., Washington DC 20585, (202) 586-1965
  115. by Bruce E. Högman of Electronic Data Systems Corporation (EDS).
  116. The author can be reached via Compuserve 72050,1327 or at the
  117. above mailing address.
  118. :p.The author was an instructor in computer sciences
  119. while on active duty with the Air Force during the
  120. Vietnam years, and has been programming since 1965 on every
  121. type of weird iron, stranger operating systems, and most
  122. popular and arcane programming languages.
  123. He's proudest of having taught US Marines at Quantico Virginia.
  124. :h2 group=14 titlebar=yes scroll=vertical rules=none id=Warn.Warranty
  125. This software is provided without warranty as a public service by the
  126. author.  Neither the author, nor the federal government or EDS
  127. Corporation makes any guarantee as to the usefulness of this software or
  128. its correct operation.
  129. :h1 hide id=EIAOS2.EIA OS/2 Application
  130. :color fc=neutral bc=neutral.
  131. :artwork name='d:\os2\bitmap\eiaos2.bmp' align=center fit.
  132. :euserdoc.
  133.