home *** CD-ROM | disk | FTP | other *** search
/ Piper's Pit BBS/FTP: ibm 0210 - 0219 / ibm0210-0219 / ibm0213.tar / ibm0213 / LS4APWAB.ZIP / LS40A.A10 / IBMLSA / IBM400P1 / VENDPROG.ZIP / README.NET < prev    next >
Encoding:
Text File  |  1994-06-10  |  17.8 KB  |  416 lines
  1.  
  2.  
  3. Setting Up Packages for VendorProg
  4. ==================================
  5.  
  6.  
  7. VendorProg is designed to support the same package structure as vendor.exe.
  8. The server and the packages remain the same.  The only difference is that
  9. the user will no longer use the vendor.exe client program because all the
  10. client code is contained in the object code for VendorProg, which is a
  11. subclass of the workplace shell WPProgram object.
  12.  
  13. The class chain for VendorProg looks like:
  14.  
  15.        SOMObject
  16.          └── WPObject
  17.                └── WPAbstract
  18.                      └── WPProgram
  19.                           └── NetProg
  20.                                 └── VendorProg
  21.  
  22. The NetProg object is defined in NETPROG.DLL which is included with VendorProg.
  23. It must also be installed on the user's machine.  If you have CORE,
  24. the coreadd for VendorProg will also add NetProg.  The NetProg class provides
  25. new functionality to the VendorProg object to enable better Network
  26. capabilities.  There are NetProg objects in the templates folder as well
  27. as VendorProg Objects.  The NetProg objects can be used for network programs
  28. that do not require vendor licenses.
  29.  
  30.  
  31.  
  32. NetProg and VendorProg Installation (non-NetDoor users)
  33. -------------------------------------------------------
  34.  
  35. To install NetProg and VendorProg, place NETPROG.DLL, VENDPROG.DLL and
  36. VNDNET32.DLL in your libpath and NOTHING.EXE somewhere
  37. on your hard drive.  Edit INSTALL.CMD to specify where NOTHING.EXE resides
  38. and where to install the Program object that points to it.  NOTHING.EXE is
  39. a windows program that does nothing.  It's purpose is to allow NetProg to
  40. change the working directory of WIN-OS/2 seamless to the local hard drive
  41. when it cannot free a network drive for a seamless program.
  42.  
  43. Run INSTALL.CMD and the classes will be registered and NetProg and VendorProg
  44. templates will be created in your templates folder.
  45.  
  46. NETPROGO.CMD is a sample that can be modified in order to create network
  47. program objects in an automated fashion.
  48.  
  49. The PMBROWSE.EXE in this zip file is the one that supports titles.
  50. The one shipped with old versions of vendor might not have this feature.
  51. Place the executable in the path or dpath of the workstation.
  52.  
  53. Creating Vendor Objects
  54. =======================
  55.  
  56. There are two ways of creating a vendor program on a user's machine.
  57.  
  58. 1. The user can open the templates folder and drag a Vendor Program object.
  59.    When the settings open, select the catalog button and choose which package
  60.    to assign to this object.  If the package has already been installed on
  61.    the user's system (as shown in the vendor.ini file), the default will be not
  62.    to re-install the package.  The "Run Install" checkbox on the package
  63.    page of the object can be checked to force a re-install.
  64.  
  65. 2. A Rexx .cmd file can be written to install a VendorProg using SysCreateObject
  66.    The syntax would be:
  67.  
  68.    rc = SysCreateObject(ClassName, ObjectTitle, Location, Setup, Flag);
  69.  
  70.    where ClassName is 'VendorProg'
  71.  
  72.          ObjectTitle is whatever title you want to give the object
  73.  
  74.          Location is either a workplace object id like '<WP_DESKTOP>' or
  75.                      the fully qualified path of the location to place the
  76.                      object
  77.  
  78.          Setup is the setup string.  At this point just use 'PACKAGE=packname'
  79.                   and let the packinst do the rest.  You want the packinst to
  80.                   do all the setup because if the user uses the templates
  81.                   folder, when the packinst runs, it will setup the object.
  82.  
  83.          Flag is 'ReplaceIfExists', 'UpdateIfExists', or 'FailIfExists'
  84.  
  85. NOTE:  Even if the package for the new object has already been installed,
  86.        the object will still call the packinst.cmd passing SETUPONLY to
  87.        tell the packinst just to setup the object and not to do the actual
  88.        file copying for the package.  This way, the packinst.cmd can
  89.        set any specific data on the object (like parameters or what executable
  90.        to run etc.) without re-installing everything.
  91.        But, if the user selects 'Run Install' on the package page, the
  92.        packinst.cmd will be run without passing SETUPONLY and the package
  93.        will fully re-install.  More on this later.
  94.  
  95.  
  96.  
  97. Migration considerations
  98. ========================
  99.  
  100. Most of the migration work needs to be done on the packinst.cmd files.
  101. One important consideration is whether or not your vendor server will be
  102. supporting users that use either the VendorProg object OR the VENDOR.EXE
  103. program.  In this case the packinst.cmd can be designed to handle
  104. both cases.
  105.  
  106. The packinst.cmd will be passed one or two parameters from the VendorProg
  107. object.  When a package re-install is not necessary but the object needs
  108. to be setup, the packinst will be passed two parameters: the OBJECT ID
  109. of the VendorProg object making the call (this object id is generated
  110. by the system and will overwrite any object ids you specify) and the
  111. string "SETUPONLY" to tell the packinst not to install the entire package.
  112.  
  113. When a package needs to be re-installed, the VendorProg object will pass
  114. only the OBJECT ID as a parameter.
  115.  
  116. NOTE:  Due to a problem with sending parameters with the '<' or '>' chars
  117.        to a program in the shell, the object id is passed without those
  118.        characters.  It is up to the packinst.cmd to ADD the brackets to
  119.        the object id before passing it through to SysSetObjectData.
  120.  
  121. If the packinst does not receive any parameters, the call is being made
  122. from the old vendor client.
  123.  
  124. So the logic of a packinst.cmd should look like this: (this is pseudo code)
  125. ---------------------------------------------------------------------------
  126.      parse arg ObjectId SetupOnly
  127.  
  128.      if SetupOnly is blank do
  129.  
  130.         Install the package on the users machine.  (just like old packinst.cmd)
  131.  
  132.      endif
  133.      else if ObjectId is not blank do
  134.         tell user you are just updating the object so they don't get confused as
  135.         to why the packinst is running when they said don't re-install.
  136.  
  137.  
  138.         add '<' and '>' to the front and end of ObjectId
  139.  
  140.         call SysSetObjectData using the newly modified object id and any data
  141.             that needs to be set on the object.
  142.  
  143.      endif
  144. ---------------------------------------------------------------------------
  145.  
  146.  
  147.  
  148. Setting Data on the Object
  149. ==========================
  150.  
  151.  
  152. The Rexx API used to set data on an object is SysSetObjectData.
  153. The first parameter is the object id and the second parameter is the
  154. setup string that specifies which object settings to modify.
  155.  
  156. The format of the setup string is:
  157.  
  158.    KEYWORD=<value>;KEYWORD=<value>;KEYWORD=<value>; etc.
  159.  
  160.    The key word specifies the setting to modify and the <Value> is the
  161.    specific value you wish to assign that setting.
  162.  
  163. The OS/2 2.0 Presentation Manager Programming Reference vol. II lists all
  164. the possible setup key words and values you can set for any object
  165. (under wpSetup) and all that can be set for a program object
  166. (which VendorProg is a descendent from) (under WPProgram).
  167.  
  168. Again, do not use the OBJECTID= keyword because the VendorProg will assign
  169. itself its own object id and overwrite yours.
  170.  
  171. Some useful keywords from WPProgram are:
  172.  
  173.     Key Word              Value
  174.     -------------------   -----------------------------------------------
  175.  
  176.     PARAMETERS            whatever parameters the program requires to run.
  177.  
  178.     PROGTYPE              FULLSCREEN      os/2 fullscreen
  179.                           WINDOWABLEVIO   os/2 window
  180.  
  181.                           PM              os/2 pm
  182.  
  183.                           VDM             dos fullscreen
  184.                           WINDOWEDVDM     dos window
  185.  
  186.                           SEPARATEWIN     (3.0)win-os2 seamless separate sess.
  187.                           WIN             (3.0)win-os2 fullscreen
  188.                           WINDOWEDWIN     (3.0)win-os2 seamless common sess.
  189.  
  190.                           PROG_31_STD     (3.1)win-os2 fullscreen
  191.                           PROG_31_STDSEAMLESSCOMMON (3.1) win-os2 seamless
  192.                           PROG_31_STDSEAMLESSVDM  (3.1) win-os2 seamless
  193.                                                   separate session
  194.  
  195.                           PROG_31_ENH     (3.1)win-os2 fullscreen enhanced
  196.                           PROG_31_ENHSEAMLESSCOMMON (3.1) win-os2 seamless
  197.                                                     enhanced
  198.                           PROG_31_ENHSEAMLESSVDM  (3.1) win-os2 seamless
  199.                                                   separate session enhanced
  200.  
  201. NOTE:  DO NOT USE EXENAME= or STARTUPDIR=  the .exe name is specified in
  202.        the package or by RUNFILE= by the packinst and the STARTUPDIR is
  203.        replaced by WORKINGDIR (more on that below...)
  204.  
  205. VendorProg is also a descendent from NetProg  (Network Program Object).
  206.  
  207. The keywords supported by NetProg are:
  208.  
  209.     Key Word         Value
  210.     -------------    --------------------------------------------------------
  211.     WDNETNAME        Network name of working directory (leave out if
  212.                      working dir to be set is on local machine)
  213.  
  214.     WDLANDRIVE       drive letter to assign WDNETNAME.  default is '*' which
  215.                      means use any drive.
  216.  
  217.     WORKINGDIR       path (not including drive letter or UNC for network paths)
  218.                      of working dir.  If the working dir is on the local
  219.                      machine, include the drive letter.
  220.  
  221.     ENVREPLACE       replace the following environment string.  (see help
  222.                      on environment page of VendorProg)  (must have a space
  223.                      before the actual string to replace)
  224.  
  225.    NOTE: env strings only work for OS/2 programs.  (not DOS or WIN-OS/2)
  226.  
  227.                      example: ENVREPLACE PATH=C:\MYPATH^;C:\ANOTHERPATH^;;
  228.                      NOTE: use the '^' for any ';' that is to be treated
  229.                            as a literal ';' to go into the path statement
  230.                            and not to separate the different setup keywords.
  231.  
  232.     ENVAPPEND        same as replace but do an append of the environment string
  233.  
  234.     ENVPREPEND       same as replace but do a prepend of the environment string
  235.  
  236.                      NOTE:
  237.                      you must provide the proper separator in the BEGINNING of
  238.                      an environment string for ENVAPPEND for any env variable
  239.                      other than PATH and DPATH. Also provide a proper separator
  240.                      at the END for ENVPREPEND for env variables other
  241.                      than PATH and DPATH.
  242.  
  243.                      Also, '?' gets replaced on execution with program network
  244.                      drive and '~' gets replaced on execution with working dir
  245.                      network drive
  246.  
  247.                      e.g. ENVREPLACE PATH=?:\MYPATH;~:\ANOTHER
  248.  
  249.  
  250.     RUNBEFORE        fully qualified path of .cmd file to run before VendorProg
  251.                      executes
  252.  
  253.     RUNBEFORESTYLE   INSTALL - run only once for this object and never again.
  254.                      ONCE - (default) run on only first instance of program
  255.                              opening
  256.                      MULTIPLE - (not supported for VendorProg) never more than
  257.                                 one running.
  258.  
  259.     RUNAFTER         fully qualified path of .cmd file to run after VendorProg
  260.                      executes
  261.  
  262.                      NOTE: RUNBEFORE and RUNAFTER are useful to replace any
  263.                            file editing that needed to be done in the packrun.
  264.  
  265.     RUNBACKGROUND    NO (default) run the RUNBEFORE and RUNAFTER .cmd files
  266.                         in the foreground
  267.  
  268.                      YES  run the RUNBEFORE and RUNAFTER .cmd files in the
  269.                          background.
  270.  
  271.     EXTRADRIVE       specify extra drives to net use when the program
  272.                      executes.
  273.                      this is in the form of netname^D^n,netname^D^n;
  274.  
  275.                  netname can be an alias or UNC path
  276.                  D is the drive letter desired ('*' for any) this is required.
  277.                  n is a number to assign this drive if you are using * and want
  278.                    to also use substitution in env strings.  (you can only have
  279.                    9 of these 1-9)  the ^n is optional.
  280.                  ^ separates netname, drive letter, and number
  281.                  , separates each separate extra drive requested
  282.  
  283.  EXAMPLE: EXTRADRIVES=myalias^*^1,\\myserv\myshare^Q;ENVREPLACE PATH=?1\mypath;
  284.  
  285.  here I want myalias assigned to any drive given the drive number
  286.  1 so it can be replaced in my PATH statement for ENVREPLACE.
  287.  note I used ?1\  the '?' tells netprog to substitute the drive
  288.  and the '1' following directly after means use extra drive 1
  289.  (if you don't put the number the program path drive will be used)
  290.  NOTE: don't put a colon.  I will replace the '?' with the drive letter
  291.      and the '1' or whatever number with a ':'.
  292.  
  293.     RUNIFFAIL    YES  if any or all of extra drives fail to get accessed
  294.                       message goes up but program will still run.
  295.  
  296.                  NO   message goes up program does not run.
  297.  
  298.                       NOTE: this is for extra drives ONLY!!!
  299.  
  300.  
  301. The keywords supported by VendorProg are:
  302.  
  303.     Key Word         Value
  304.     -------------    --------------------------------------------------------
  305.     PACKAGE          package name to use for this VendorProg object
  306.  
  307.     RUNFILE          Executable to run if different from the run file
  308.                      specified in the package definition.  This is for
  309.                      migration if there are people using the old vendor
  310.                      client for this package and still need to packrun.cmd
  311.                      to run for them but VendorProg will run the .exe
  312.                      directly.
  313.                      VendorProg will add <landrive>:\ to the front of
  314.                      the name.
  315.  
  316.                      Also use this if the run file is on the local machine
  317.                      (in that case use drive letter)
  318.  
  319.     LANDRIVE         If package is set to always use the same lan drive
  320.                      but the user can choose which one, the packinst has
  321.                      to option to query the user for the drive letter and
  322.                      then pass it through to the object.  If LANDRIVE
  323.                      isn't used, the user can set the drive on the
  324.                      Package page of the settings notebook.
  325.  
  326.  
  327.  
  328. Object Settings Notebook
  329. ========================
  330.  
  331. The VendorProg class adds the Package page to the settings notebook of
  332. the object.  This enables the user to change which package this object
  333. points to.  The Vendor.ini file keeps record of any time a specific packinst
  334. was run, which lan drive they were assigned (if relevant)
  335. and whether or not the install program had been run yet.  All other
  336. data is stored locally to the VendorProg object itself.
  337.  
  338. The Package page is also where users can specify parameters for the
  339. vendor program.
  340.  
  341. When the settings notebook is opened, VendorProg tries to get a
  342. license so the workplace shell can access the executable on the lan
  343. which enables the session page to work properly.  This license
  344. will use any available drive and the settings notebook must be closed
  345. before running the VendorProg object.
  346.  
  347. The Working Dir, Environment, and Command File pages are added by
  348. NetProg.  These provide the settings described before for NetProg.
  349. WPProgram adds the Session and Association pages.  The association page
  350. currently does not work due to a bug in OS/2 that will be fixed in
  351. version 2.2.  The Window and General pages are added by WPObject.
  352.  
  353.  
  354. Do You Need a Packrun.cmd?
  355. ==========================
  356.  
  357. In almost all cases you can configure a VendorProg from the packinst.cmd
  358. so it does not require a packrun.cmd.  Here are some common uses of
  359. the packrun.cmd and how the function can be ported into the object itself:
  360.  
  361. 1.  Edit the autoexec.bat before and after execution of the program:
  362.  
  363.     Set the RUNBEFORE and RUNAFTER settings on the object to point
  364.     to .cmd files to perform the action.
  365.  
  366.     OR on OS/2 2.1 'SET DOS_AUTOEXEC=DiffExec.bat' in setup string.
  367.  
  368. 2.  Pass special parameters.
  369.  
  370.     use PARAMETERS= in packinst.cmd when setting data on the object.
  371.  
  372. 3.  Change PATH or other environment strings (os/2 programs only).
  373.  
  374.     use ENVREPLACE, ENVAPPEND or ENVPREPEND setup strings in packinst.cmd
  375.  
  376. 4.  Net use other drives
  377.  
  378.     use EXTRADRIVES setup string in packinst.cmd
  379.  
  380.  
  381. If you can replace all functions of the packrun.cmd for a specific package
  382. with VendProg features and you do not need to support old client users,
  383. have the package definition point directly to the executable name.
  384.  
  385. If you must support users on the old client, keep the package definition
  386. pointing to the packrun.cmd and have the packinst.cmd tell VendorProg
  387. to use the executable (RUNFILE= in setup string).
  388.  
  389. WINSTART.EXE           Used to run programs like project and Microsoft Word
  390.                        That can't run on OS/2 2.1 because they require
  391.                        a working directory different from where the executable
  392.                        exists.
  393.  
  394. NOTE: The current icon for WINSTART.EXE isn't very nice.  We are going to
  395.       fix it soon.  It is very easy to write the program, though.  It
  396.       looks  like this:  (you need a windows SDK)
  397.  
  398.  
  399. /*-------------------------------------------------------------------------*/
  400. /* WinStart - a "Windows Start-a-Program Program"
  401. /*
  402. /* Gunnar Seaburg            6/93
  403. /* IBM Corp.
  404. /*-------------------------------------------------------------------------*/
  405. #include <windows.h>
  406. /*-------------------------------------------------------------------------*/
  407. /* Main
  408. /*-------------------------------------------------------------------------*/
  409. int PASCAL WinMain (HANDLE hInstance, HANDLE hPrevInstance,
  410.                     LPSTR lpszCmdLine, int nCmdShow)
  411. {
  412.      return WinExec (lpszCmdLine, SW_SHOW);
  413. }
  414.  
  415.  
  416.