vms/README

   1 --------------------------------------------------------------------------------
   2 Fvwm with OpenVms, how-to
   3 Fabien Villard (Villard_f@Decus.Fr), February 1999
   4 --------------------------------------------------------------------------------
   5
   6         Versions :
   7         ----------
   8
   9         Fvwm 2.3 official version.
  10         OpenVms Alpha V7.1-1H1, DecC V5.7-006
  11
  12
  13
  14         Thanks
  15         ------
  16
  17         Thanks to  the fvwm team and especially to Steve Robbins who worked with
  18 me to integrate the OpenVMS port in the source tree.
  19
  20
  21
  22         Compilation
  23         -----------
  24
  25 Set Default to <top of source tree>.
  26
  27 Copy [.Vms]Make_Fvwm.Mms to <top of source tree>.
  28
  29 Copy [.Vms]Vms_Shareables.Opt <to top of source tree>.
  30
  31 Edit  the  Make_Fvwm.Mms  file   and  modify  the  first  macros  to  suit  your
  32 environment.
  33
  34 Copy [.Vms]Config.h file to <top of source tree>Config.h.
  35
  36 Edit the Config.h file and  modifiy  what you want, according to the comments in
  37 it.  Especially, deactive all XPMlibraries  uses if you don't have them or don't
  38 need this support.
  39
  40 Copy [.Vms]/vms.c and [.Vms]/vms.h into <top of source tree>[.Libs].
  41
  42 Then do a
  43         $ Mms/Descript=Make_Fvwm.Mms/Ignore=Warning.
  44 This  will  create  the fvwm executable Fvwm.Exe  in  [.Fvwm]  and  the  modules
  45 executables FvwmXxx.Exe in the directory [.Modules.Bin].
  46
  47
  48         Installation
  49         ------------
  50
  51 Copy the images Fvwm.Exe and FvwmXxx.Exe where appropriate.
  52
  53 Extract from the end of this README and  edit the Fvwm_Ope.Com procedure, mofify
  54 the logical names to reflect your environment.  The Fvwm distribution contains a
  55 set  of icons, pixmaps and miniicons in the [.icons] directory.    They  can  be
  56 moved  to  a  more  appropriate  place.  Put this file where  it  goes  in  your
  57 environment.
  58
  59 Copy the FvwmRc.Dat file in your Sys$Login.  Edit it.  The  sample  is  provided
  60 just for a quickstart.  The docs can be found in the files  *.1  (Unix manpages,
  61 no time to convert them) in [.fvwm] and [.modules.FvwmXxx]FvwmXxx.1 directories.
  62
  63 In your  Sys$Login,  you  have a VUE$PROFILE.VUE$DAT file.  Save it, for example
  64 under the name VUE$PROFILE.VUE$DAT_MOTIF.
  65
  66 Open DecWindow "Menus..." option of the Session Menu Bar.
  67
  68 Create a new "Item name", say "Fvwm", with the following command :
  69         @<Fvwm_Ope.Com path>Fvwm_Ope.Com
  70
  71 Open DecWindow "Automatic  Startup..."  entry of the Session Menu Bar.  Kill the
  72 "Window Manager" entry and add instead the newly created "Fvwm" item.
  73
  74 Save the session manager options.
  75
  76 Now in your Sys$Login,  the  modification  timestamp  of VUE$PROFILE.VUE$DAT has
  77 changed.       Save  the  new    form,    for    example    under    the    name
  78 VUE$PROFILE.VUE$DAT_FVWM.
  79
  80 Close the session and reopen it. Fvwm must run.
  81
  82
  83         If it goes wrong
  84         ----------------
  85
  86 If Fvwm doesn't run, or run and die, but the XServer is still there, no problem.
  87 Just open a new DecTerm.  It  will  popup  on top of the windows list.  Click in
  88 it, it gets the focus.  Then do something like
  89         Copy VUE$PROFILE.VUE$DAT_MOTIF VUE$PROFILE.VUE$DAT
  90
  91 CLose the session, reopen it, Mwm will run.
  92
  93 Some informations can be found in the file Fvwm.Log in your Sys$Login.  In vms.h
  94 there  are  some  debugguing  macros  that  can  be  activated  to  trace  more.
  95 Especially,  the  one  that  enable flush and/or open/close of the  trace  file.
  96 Attention it slows the fvwm start a lot.
  97
  98 All  that  precedes can be accomplished with only TmpMbx and NetMbx  privileges.
  99 Next, if you are unlucky, need more privileges, or less kindness :-)
 100
 101 If  the  XServer  die unexpectadly (Quotas limits, file protections...), you can
 102 restart it  from  the  console, or from another machine, or, you can reboot your
 103 ws.  That's  not  very  fair,  but...  In both cases, don't forget to manage the
 104 copy above.
 105
 106
 107 --------------------------------------------------------------------------------
 108 Fvwm under OpenVms, modifications list
 109 Fabien Villard (Villard_F@Decus.Fr), 20-JAN-1999
 110 --------------------------------------------------------------------------------
 111
 112         Fvwm configuration :
 113         --------------------
 114
 115 The file VMS_config.h is derived from the config.h.in generated by autoconf.  It
 116 can be edited to modify  the  system configuration (HAVE_xxx, ...) and the stuff
 117 you want in Fvwm (SHAPE, ...).
 118
 119         Some things are added here to  help  debugguing the VMS port, and others
 120 ARE the port :-) :
 121
 122         #include "vms.h" :  this gives acces to the VMS stuff for all sources of
 123 Fvwm without modifying them.
 124
 125         #define fork vfork :  in my version  of  DecC I haven't fork, but vfork.
 126 See more on this later.
 127
 128         #define execvp execv :  this avoid using the  PATH  environment variable
 129 and  with a minor modification of code, allows to use  logicals  to  locate  the
 130 modules.
 131
 132         #define execl VMS_ExecL :  the new function VMS_ExecL() gets the command
 133 Unix'ly  passed  to  the  shell,  splits  it  in words and rebuild an  array  of
 134 arguments.    Then  it calls execv(), assuming it has found an image name.    If
 135 execv() call  fails,  VMS_ExecL() returns 0, hiding the fail.  Thus the original
 136 code, executing in  the  parent  context, doesn't call exit() which is fatal for
 137 the parent with actual version of Dec C RTL.
 138
 139         #define fvwm_msg VMS_msg :    there  is  a  coredump  I can't figure out
 140 (quotas)  when  using  the  fprintf(stderr,...)    function   to  display  debug
 141 informations.  DecWindows crashes with a generic error 65535, probably meaning a
 142 VMS IO error.  I give in  Vms.c  another  tracing function wich can be forced to
 143 open/close the output file, or to flush outputs (it could be cool to get the the
 144 image name of the process running to display in the log file or to have separate
 145 logs for each modules, if someone is interested in adding it)
 146
 147         #define  select VMS_select_pipes :  that's the big deal.   The  select()
 148 function is not working as expected and we cannot give it  the X file descriptor
 149 wich  under  VMS  is  an  event  flag.    So  I rewrote the  select()  function,
 150 considering the C pipes are implemented as MailBoxes under VMS.
 151
 152
 153         New sources :
 154         -------------
 155
 156         Vms.c/Vms.h : contains specific functions for VMS.
 157
 158
 159         Sources modifications :
 160         -----------------------
 161
 162 [.Fvwm]Fvwm.c
 163                   because  DecWindow  gives  an  event  flag  instead  of  a file
 164 descriptor in  the  fd field of the Display structure, we cannot use the fcntl()
 165 function with it.  I don't know if we could get the fd, or even if there is one.
 166 So we must comment  the  fcntl() call on X file descriptor.  If DecWindow uses a
 167 file descriptor (I guess no), it will remain open in the subprocesses spawned by
 168 exec() functions family.  If it doesn't use one, no consequences.
 169
 170 [.fvwm]module.c
 171                   o When the fork/exec functions are  used with Unixes, the code
 172 between the fork() and the exec() is  executed  by the child process.  With VMS,
 173 it is executed by the parent process, for  the  child doesn't exist yet.  So, we
 174 cannot close the parent pipes that the child doesn't need.
 175                   o Despite the fact that there is code to  verify the existence
 176 of the image to run in a child process, the  child  process  spawning  can  fail
 177 (protections, quotas,...) more easely than under Unix.  The exec() function then
 178 returns just after the call and the original code exits.  I  think  with  VMS it
 179 must not be considered a fatal error.
 180
 181 [.fvwm]misc.c
 182                   Just comment out the  original fvwm_msg() function to activate
 183 the VMS_msg().
 184
 185 [.fvwm]module.c
 186                   The image names are traditionnaly built wit a ".exe" extension
 187 in VMS and without extension in  Unix.    To  limit the incompatibilities in the
 188 Fvwm resource files, speaking of module names,  I add temporarily this extension
 189 to the file name searched, when the file type is executable.  So, apart from the
 190 actual locations of things, the syntaxe of the resource file is not changed.
 191
 192 [.modules.fvwmpager]fvwmpager.c
 193                   o  Due  to  the  VMS_select_pipes()  implementation  (see  the
 194 source), some  ghosts X events can be generated.  Depending upon the way returns
 195 from the function  are  managed,  this  can  lead  to  false  "missed X events".
 196 Fvwmpager.c exits when those  missed  X  events  are to numerous.  I bypass this
 197 test.
 198
 199 [.modules.fvwmwinlist]fvwmwinlist.c
 200                   o Probably due to DecWindow  events  buffering,  I must add an
 201 XFlush() call to have the window really redrawn.
 202
 203
 204
 205         Fvwm unused sources :
 206         ---------------------
 207
 208         [.Libs]usleep.c
 209         [.libs]strerror.c
 210         [.Libs]strcasecmp.c
 211         [.Libs]strncasecmp.c
 212
 213
 214 --------------------------------------------------------------------------------
 215 Fvwm with OpenVms, DCL procedures
 216 Fabien Villard (Villard_f@Decus.Fr), 28-JAN-1999
 217 --------------------------------------------------------------------------------
 218
 219         FVWM_OPE.COM : launch Fvwm from the DecWindow session manager.
 220         SHSUBPROC.COM : is a small utility to view the processes involved in
 221 Fvwm execution. Launch it with :
 222                 $ @SHSUBPROC DECW$SESSION
 223
 224 ----------- FVWM_OPE.COM --------------------------------------------------
 225 $!      Set Process/Dump
 226 $! --- Location of the Fvwm images ---
 227 $       Assign/NoLog Fab$Exe fvwm_bindir
 228 $! --- Location of the pixmaps  ---
 229 $       Assign/NoLog DARC:[VMS.Pixmaps] fvwm_pixdir
 230 $! --- Location of the icons ---
 231 $       Assign/NoLog DARC:[VMS.Icons] fvwm_icodir
 232 $       Run/NoDebug Fab$Exe:fvwm.Exe
 233 $       Exit
 234 ----------- FVWM_OPE.COM --------------------------------------------------
 235
 236
 237 ---------- SHSUBPROC.COM --------------------------------------------------
 238 $       Verbose = 0
 239 $       Say :== Write Sys$Output
 240 $       If P1 .Eqs. ""
 241 $       Then
 242 $         Say "P1 : Master Process Name"
 243 $         Goto EndScript
 244 $       EndIf
 245 $       MasterName = P1
 246 $!
 247 $       ProcessContext = ""
 248 $       A = F$Context("Process", ProcessContext, "PRCNAM", MasterName, "Eql")
 249 $       MasterPid = F$Pid(ProcessContext)
 250 $       If MasterPid .Eqs. "" Then Goto EndScript
 251 $       If Verbose .Eq. 1 Then Say "---------- Pid of Decw$Session process : " + MasterPid
 252 $       NbProc == 1
 253 $       Level == 0
 254 $       Call DisplayProcess 'MasterPid
 255 $       Call ListSubProc 'MasterPid
 256 $       Say "There are ", NbProc, " processes in this job."
 257 $EndScript:
 258 $       Exit
 259 $!
 260 $ListSubProc: SubRoutine
 261 $       Level == Level + 1
 262 $       Owner = P1
 263 $       If Verbose .Eq. 1 Then Say "---------- Listing subprocesses of ", Owner
 264 $       SubContext = ""
 265 $       A = F$Context("Process", SubContext, "OWNER", Owner, "Eql")
 266 $NextProcess:
 267 $       Pid = F$Pid(SubContext)
 268 $       If Pid .Eqs. "" Then Goto NoMoreProcess
 269 $       NbProc == NbProc + 1
 270 $       Call DisplayProcess 'Pid
 271 $       Call ListSubProc 'Pid
 272 $       Goto NextProcess
 273 $!
 274 $NoMoreProcess:
 275 $       Level == Level - 1
 276 $       If Verbose Then Say "---------- End ", Owner
 277 $EndSubroutine
 278 $!
 279 $DisplayProcess:SubRoutine
 280 $       Pid = P1
 281 $       PrcNam = F$GetJpi(Pid, "PrcNam")
 282 $       ImagName = F$GetJpi(Pid, "ImagName")
 283 $       ModuleName = F$Parse(ImagName,"","","NAME","SYNTAX_ONLY")
 284 $       FormPrcNam = F$Fao("!#AS!AS", Level*2, "", PrcNam)
 285 $       Say F$Fao("!22AS  !8AS  !12AS", FormPrcNam, Pid, ModuleName)
 286 $EndSubroutine
 287 ---------- SHSUBPROC.COM --------------------------------------------------