home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / skeleton.zip / Skeleton.cmd < prev    next >
OS/2 REXX Batch file  |  1995-08-03  |  18KB  |  346 lines
  1. /*****************************************************************************\
  2. | Standard skeletal structure for new REXX programs.                          |
  3. |                                                                             |
  4. | Libraries:   REXXSAA                                                        |
  5. |  Category:                                                                  |
  6. |     Class:                                                                  |
  7. |      Type:                                                                  |
  8. |    Author:   Bob Rice - CompuServe: 72421,3016                              |
  9. |                                                                             |
  10. | Copyright (c) 1995 Empirical Heuristics                                     |
  11. \**************************************************************************r4*/
  12.   EH. = ''                                      /* Initialize global stem    */
  13.   /*=========================================================================*\
  14.   | >>>>> NOTE:  You should set the values of the next three variables! <<<<< |
  15.   | The dollar signs in the strings Revision: and Date: may be removed, if    |
  16.   | desired.  They are there to permit automated source code version control. |
  17.   \*=========================================================================*/
  18.   EH.pgm_ver  = '$Revision:   1.0  $'           /* Version number of program */
  19.   EH.pgm_date = '$Date:   03 Aug 1995 20:10:24  $' /* Revision date of pgm   */
  20.   EH.reqd_params = 0                            /* Number of required params */
  21.   parse arg args; call Prolog args; drop args; signal on error; signal on halt
  22.   signal on failure; signal on novalue; signal on syntax; if EH.trace\='' then
  23.   say '--> Entering' EH.pgm_filespec; trace value EH.trace; nop
  24. /*------------------------------------------------------End Skeletal Header--*/
  25.  
  26.   /***************************************************************************\
  27.   |                              START OF PROGRAM                             |
  28.   \***************************************************************************/
  29.   /*>>>>>>>>>>>>>>>>>>>>>>>>>> your code goes here <<<<<<<<<<<<<<<<<<<<<<<<<<*/
  30.   exit
  31.  
  32.   /***************************************************************************\
  33.   |                            PROGRAM SUBROUTINES                            |
  34.   \***************************************************************************/
  35.   /*>>>>>>>>>>>>>>>>>>>>>> your procedures can go here <<<<<<<<<<<<<<<<<<<<<<*/
  36.  
  37.   /*=========================================================================*\
  38.   | This routine will be called when an error is trapped.  It is called after |
  39.   | all error handling is completed.  You may insert your own code here to do |
  40.   | cleanup and whatever else is necessary for your program on abnormal exit. |
  41.   | But DO NOT DELETE THIS ROUTINE; it is required for proper operation.      |
  42.   \*=========================================================================*/
  43. ErrorExit:
  44.   return
  45.  
  46. /*****************************************************************************\
  47. |                          REQUIRED SKELETAL PROLOG                           |
  48. \*****************************************************************************/
  49. Prolog: procedure expose EH.
  50.                 EH.prolog_ver = '1.0'
  51.   if pos(':',EH.pgm_ver)  > 0 then parse var EH.pgm_ver ':' EH.pgm_ver '$'
  52.   EH.pgm_ver = strip(EH.pgm_ver)
  53.   if pos(':',EH.pgm_date) > 0 then do           /* Extract date from string  */
  54.     parse var EH.pgm_date ':' d m y . '$'
  55.     EH.pgm_date = strip(d m y); drop d m y
  56.   end
  57.   parse arg     EH.cmd_line
  58.   parse version EH.REXX EH.REXX_ver EH.REXX_date
  59.   parse source  EH.os EH.calling_environ EH.pgm_filespec
  60.   if EH.os = 'OS/2' then do QueCmd('VER'); pull EH.os_ver
  61.     if EH.os_ver \= '' then EH.os_ver = word(EH.os_ver,words(EH.os_ver))
  62.   end
  63.   EH.environ  = 'OS2ENVIRONMENT'
  64.   EH.pgm_fnfe = filespec('N',EH.pgm_filespec)
  65.   EH.pgm_path = filespec('D',EH.pgm_filespec) || filespec('P',EH.pgm_filespec)
  66.   parse var EH.pgm_fnfe EH.pgm_fn '.' EH.pgm_fe; arg help .
  67.   if wordpos(help,'? ?? ??? ???? /? /H /HELP -H -HELP') > 0 then call Tell help
  68.   if EH.reqd_params > words(EH.cmd_line) then call Tell '??'
  69.   /*--------------------------------------------------------------*\
  70.   |  Get trace value first from the environment, then overwrite it |
  71.   |  if it is also specified on the command line.  Also get debug. |
  72.   \*--------------------------------------------------------------*/
  73.   EH.trace = value('TRACE',,EH.environ)
  74.   t = wordpos('/TRACE',translate(EH.cmd_line))
  75.   if t > 0 then EH.trace = word(EH.cmd_line, t+1)
  76.   EH.debug = value('DEBUG',,EH.environ)
  77.   if EH.debug \= 1 then EH.debug = 0
  78.   d = wordpos('/DEBUG',translate(EH.cmd_line))
  79.   if d > 0 then EH.debug = 1
  80.   /* Remove /DEBUG and /TRACE params from EH.cmd_line */
  81.   tmp = ''
  82.   do i = 1 to words(EH.cmd_line)
  83.     if i = t | i = t + 1 | i = d then iterate
  84.     tmp = tmp word(EH.cmd_line,i)
  85.   end
  86.   EH.cmd_line = strip(tmp); drop d t tmp
  87.   if FuncReg() = 0 then return                  /* Register external funcs   */
  88.                    else exit 255
  89. Tell: procedure expose EH.                      /* Display help information  */
  90.   parse arg help
  91.   call TellHelp help, EH.pgm_filespec, EH.pgm_ver, EH.pgm_date, EH.prolog_ver
  92.   exit 254
  93. /*===========================================================================*\
  94. |                               Trap Routines                                 |
  95. \*===========================================================================*/
  96. Error:   call ProcessTrap SIGL, 'ERROR',   rc
  97. Failure: call ProcessTrap SIGL, 'FAILURE', rc
  98. Halt:    call ProcessTrap SIGL, 'HALT',    ''
  99. NoValue: call ProcessTrap SIGL, 'NOVALUE', ''
  100. Syntax:  call ProcessTrap SIGL, 'SYNTAX',  rc
  101. ProcessTrap:
  102.   if pos(':',EH.pgm_filespec) > 0 then TRAP.source_line = ,
  103.     strip(sourceline(arg(1)))            /* Get source line if available     */
  104.   else do                                /* Program is running in macrospace */
  105.     TRAP.path_and_program = value('TEMP',,EH.environ) || TRAP.path_and_program
  106.     TRAP.source_line = 'Source line is not available.'
  107.   end
  108.   EH.dump_file = ErhTrap(arg(1),arg(2),arg(3),EH.pgm_filespec,TRAP.source_line)
  109.   if EH.dump_file  \= '' then do      /* Create DMP file if appropriate      */
  110.     call SysFileDelete EH.dump_file
  111.     drop TRAP. RC RESULT SIGL         /* Remove meaningless vars for clarity */
  112.     call VarDump EH.dump_file         /* Write variables to program.DMP file */
  113.   end
  114.   erc = ErhTrap('FINISH_UP',EH.dump_file,EH.pgm_filespec,arg(1)) /* Finish up*/
  115.   call ErrorExit
  116.   exit erc
  117.  
  118.   /***************************************************************************\
  119.   |                              DEBUG ROUTINES                               |
  120.   |                                                                           |
  121.   | The routines below this point in the code are not part of the skeleton    |
  122.   | or the error handler and are not necessary for its proper operation.      |
  123.   | These routines may prove useful for debugging during program development  |
  124.   | and as such are included here for convenience.  You may delete them after |
  125.   | program development is completed and before program release.              |
  126.   \***************************************************************************/
  127.  
  128.   /*=========================================================================*\
  129.   | Debug routine to dump accessible vars to a sorted file.  The filename is  |
  130.   | the line number from which the call is made and the file extent is .V.    |
  131.   | The directory is the current directory.                                   |
  132.   |                                                                           |
  133.   | Params: [ var-list ] [, { I | E }]                                        |
  134.   |                                                                           |
  135.   |   var-list    is a quoted list of variable names separated by blanks.     |
  136.   |                                                                           |
  137.   |   [ I | E ]   determines whether the listed variables are to be included  |
  138.   |               or excluded.  Included is the default.                      |
  139.   |                                                                           |
  140.   | Example: 'i j k lines.', 'e'                                              |
  141.   |                                                                           |
  142.   | 06/01/95 - REXXSAA, REXXLIB                                               |
  143.   | (c) 1995 Empirical Heuristics                                             |
  144.   \*=========================================================================*/
  145. DumpV:
  146.   parse arg _dumpv.str, _dumpv.ie
  147.   _dumpv.file = sigl'.V'
  148.   call SysFileDelete _dumpv.file
  149.   if _dumpv.str \= '' then do
  150.     _dumpv.list = ''''word(_dumpv.str,1)''''
  151.     do _dumpvi = 2 to words(_dumpv.str)
  152.       _dumpv.list = _dumpv.list || ','''word(_dumpv.str,_dumpvi)''''
  153.     end
  154.   end
  155.   else _dumpv.list = ''
  156.   if _dumpv.ie = '' then _dumpv.ie = 'I'
  157.   if _dumpv.list = ''
  158.     then call VarDump _dumpv.file
  159.     else interpret 'call VarDump _dumpv.file, _dumpv.ie,' _dumpv.list
  160.   call FileRead _dumpv.file, '_dumpv.',, 'E','CRANDLF'
  161.   call ArraySort '_dumpv.'
  162.   call FileWrite _dumpv.file,'_dumpv.','R'
  163.   say 'Variable data dumped to file' _dumpv.file'.'
  164.   drop _dumpv. _dumpvi
  165.   return
  166. /*--Begin Help-----------------------------------------------------------------
  167. This section is the help text.
  168.  
  169. Params:
  170.  
  171. where:
  172.  
  173. ________________
  174. Alternate Params: [ ? | ?? | ??? | ???? ]
  175.  
  176. where:
  177.  
  178.   ?     Displays up to the "Syntax:" or "Params:" portion of this help text.
  179.  
  180.   ??    Displays this entire help text except for the technical information.
  181.  
  182.   ???   Displays this entire help text.
  183.  
  184.   ????  Puts this help text into a file whose name is the same as the name of
  185.         this program and whose extent is .ABS.  The file is written to the same
  186.         directory as that in which this program resides.
  187.  
  188. _______________
  189. Technical Notes
  190.  
  191. >>>>>  IMPORTANT - IMPORTANT - I M P O R T A N T - IMPORTANT - IMPORTANT  <<<<<
  192.  
  193. Several lines in this skeletal structure contain strings which will be used by
  194. an update program to update the skeleton in your program to a newer version
  195. should one become available.  It is extremely important that these lines be
  196. present in their original relative locations and that the strings within these
  197. lines remain intact.  Any disturbance may cause the update program to fail when
  198. upgrading the skeletal structure of a program you have developed based on the
  199. Skeleton.  The strings which must not be disturbed are:
  200.  
  201.              "--End Skeletal Header--"
  202.              "REQUIRED SKELETAL PROLOG" and the line above it
  203.              "--Begin Help--"
  204.              "--End Help--"
  205.  
  206. In addition, except for changing the values of three variables, as noted below
  207. in the section "Global" Variables, do not change any of the lines between the
  208. header comment box and the "--End Skeletal Header--" line.
  209.  
  210. Also, do not delete the ErrorExit procedure.  It is okay to leave it empty, but
  211. it must remain in your code.
  212.  
  213. Finally, do not delete the REQUIRED SKELETAL PROLOG comment box, or any of the
  214. code following it.  It is okay, however, to delete the DumpV procedure, its
  215. comment header, and the DEBUG ROUTINES comment box, if you wish to do so.
  216.  
  217. ____________________
  218. Debugging Assistance
  219.  
  220. The keyword parameter /DEBUG may be added to the invocation line.  This will
  221. set the variable EH.debug to 1. You can then use this variable in your code to
  222. selectively execute code when /DEBUG is specified as a parameter.  If /DEBUG is
  223. not specified, EH.debug is set to 0. You may also set an environment variable
  224. called DEBUG to either 0 or 1 to accomplish the same thing.  The /DEBUG
  225. parameter will override the DEBUG environment variable.
  226.  
  227. The keyword parameter /TRACE followed by a valid trace argument may be added to
  228. the end of the invocation line to initiate tracing as, for example:  /TRACE ?r
  229. You may also set an environment variable called TRACE to a valid REXX trace
  230. parameter to accomplish the same thing.  The /TRACE parameter will override the
  231. TRACE environment variable.
  232.  
  233. ____________
  234. Help Display
  235.  
  236. The four parameters ?, ??, ???, and ????  display various levels of help
  237. extracted from the embedded help information.  See the help in TellHelp.cmd for
  238. a fuller explanation of what these do.  Knowing what these four parameter
  239. values do will assist you in preparing your own embedded help information.
  240.  
  241. Note that when help is requested by the user, none of your code is executed.
  242.  
  243.  
  244. Help Content
  245.  
  246. The section of this embedded help entitled Technical Notes is quite extensive
  247. and intended for the programmer rather than the user.  I suggest that you
  248. delete the entire Technical Information section from your own embedded help to
  249. reduce the bulk of your programs.
  250.  
  251. What you write for embedded help is, of course, up to you.  But I suggest you
  252. leave in it the section called Alternate Params, since a users of your programs
  253. could not guess that additional help is available for the asking.  Of course,
  254. if you don't include any additional help after the "Params:" or "Syntax:"
  255. line, then by all means delete the Alternate Params section.
  256.  
  257. Whatever you decide to do, be sure not to delete the "--End Help--" marker
  258. line!
  259.  
  260. __________________
  261. "Global" Variables
  262.  
  263. Several variables are initialized by Skeleton before your code begins to
  264. execute.  Some of these provide information to the Skeleton for use in handling
  265. errors and processing help requests; others do not.  All can be referred to in
  266. your own code to save you from having to set similar variables yourself.  You
  267. should not change the value of any of them.  Here is the list of variables:
  268.  
  269.   EH.calling_environ    can be 'COMMAND', 'SUBROUTINE', or 'FUNCTION'
  270.   EH.cmd_line           everything after program name except: the /DEBUG para-
  271.                         meter, the /TRACE parameter and the token following it,
  272.                         and any extraneous spaces before, after and between
  273.                         parameters
  274.   EH.debug              can be 0 or 1
  275.   EH.environ            'OS2ENVIRONMENT' for OS/2
  276.   EH.os                 'OS/2' for OS/2
  277.   EH.os_ver             '3.00' for OS/2 Warp
  278.   EH.pgm_fe             program file extent - 'cmd' normally
  279.   EH.pgm_filespec       complete drive, path, filename and extent as one token
  280.   EH.pgm_fn             the name of the program excluding the '.' and extent
  281.   EH.pgm_fnfe           the filename and extent with '.' as one token
  282.   EH.pgm_path           the drive and path including trailing '\'
  283.   EH.prolog_ver         the version of the prolog (Skeleton) code
  284.   EH.REXX               the REXX interpreter used - 'REXXSAA' for OS/2 REXX
  285.   EH.REXX_date          the date of the REXX interpreter version as dd mmm yyyy
  286.   EH.REXX_ver           the version of the REXX interpreter - '4.00' for Warp
  287.   EH.trace              null or a valid REXX trace parameter if set correctly
  288.  
  289.   EH.pgm_ver            the version number of your program up to six characters
  290.   EH.pgm_date           the date of your program version as dd mmm yyyy
  291.   EH.reqd_params        the number of parameters your program requires,
  292.                         excluding optional parameters (see below)
  293.  
  294. Note that you must set the values of the last three variables yourself.  You'll
  295. find these just above the START OF PROGRAM comment box.
  296.  
  297.  
  298. EH.reqd_params
  299.  
  300. The purpose of this variable is to force the display of help information, at
  301. the ? level, in the event the program is invoked with fewer than the number of
  302. required parameters, presumably because the user has made an error and needs
  303. help.  It has no other effect.  If you don't want help for your program to be
  304. forced, then leave this value set to 0.
  305.  
  306.  
  307. Handling EH. Variables
  308.  
  309. The REXX language makes no provision for true global variables, so we must
  310. simulate this need.  All the variables required for the proper operation of the
  311. Skeleton are available as elements of the EH. stem array.  The values of these
  312. variables must be available to every part of your code.  This presents a
  313. problem inside the code of your procedures when the REXX keyword instruction
  314. PROCEDURE is used.  This instruction prevents your procedure code from seeing
  315. the EH. variables.  To circumvent this, YOU MUST USE THE EXPOSE OPTION TO MAKE
  316. THESE VARIABLES AVAILABLE TO YOUR PROCEDURE CODE.  For example, if you have a
  317. procedure called MyProc which uses the PROCEDURE instruction, then do this:
  318.  
  319.   MyProc: procedure expose EH.
  320.     /* ...your procedure code goes here... */
  321.     return
  322.  
  323. This ensures the availability of the required variables.  If you don't expose
  324. EH. to your procedure code, then Skeleton cannot process any errors occuring
  325. within the code.
  326.  
  327. Procedures not using the PROCEDURE instruction need not use EXPOSE; indeed,
  328. that would be a syntax error.
  329.  
  330. _______________________
  331. Predefined return codes:
  332.  
  333.   Code  Meaning
  334.   ----  -------------------------------------------------
  335.    254  Display of internal help was requested or forced.
  336.    255  Failure in external function registration.
  337.  
  338. ___________________
  339. Development History
  340.  
  341. $Log:   Q:/rxdv/skeleton/vcs/skeleton.cm!  $
  342.   
  343.      Rev 1.0   03 Aug 1995 20:10:24
  344.   Initial revision.
  345. --End Help-------------------------------------------------------------------*/
  346.