REXX Coding Standards Better Practices Or what we

REXX Coding Standards. . . “Better” Practices Or: what we learned “on the job” VM Workshop, June 2017 Ohio State University Contact: Mike Walter – Walter. The. Pennyless (at) hotmail. com Mobil: 847. 975. 6477 See the “Notes” pages in this presentation for additional details 1

MANDATORY “BRAG SHEET” OR: “WHY SHOULD WE LISTEN TO HIM? ” • Started as a “Teleprocessing Operator” at Kraft in Feb 1972 Thus, in “Data Processing” for over 44 years! • VM-exclusive (mostly) since 1978 (38+ years of VM!) (Beginning with VM 370 Release 5 Program Level Change 6) • Ordered VM at Hewitt Associates in Dec 1984, installed VM HPO Jan 1985 with an MVS ‘preferred’ guest, installed PROFS and migrated hundreds of active IDs from IBM services • Chaired CAVMEN for 6+ years (June 1984 -Oct 1990; 6. 5 years), still attend and contribute while retired • Member of SHARE Linux & VM Technical Steering Committee June 1997 -July 2011): Chairman 2006 -2011(6 years) • Chairman VM Workshop, Inc 2013 & 2014; continue contributions to the Volunteer Committee even now while retired • According to envelopes of various mailings: CIO; Partner-In-Charge; and Chief Cook • Currently CEO of my own happy retirement All you have to do is: out-last bad management. 2

How THIS sysprog learned to do it… … after years of learning from other VM’ers. DISCLAIMER: (YOU EXPECTED SOMETHING ELSE? ) - YOUR MILEAGE MAY VARY - For me: REXX standards are always an area of “CONTINUOUS QUALITY IMPROVEMENT” 3

AGENDA • Where can I look for help? • Better Practices: The Importance of Standards • Better Practices: REXX file formatting standards • Better practices: (CYA) • Free REXX-related Tools Miscellany 4

WHERE CAN I LOOK FOR HELP? Obviously: IBMLink (leverage your support dollars) www. ibm. com/ibmlink IBM Publications http: //www. vm. ibm. com/library (The IBM VM library) (I prefer to use the PDF links on that page, e. g. z/VM V 6. 4 publication PDF files ) http: //www. elink. ibm. com/public/applications/publications/cgibin/pbi. cgi? CTY=US (the IBM Publications Center) Informal but VERY prompt, helpful, and flameless discussion lists Send email text to: LISTSERV@LISTSERV. UARK. EDU SUBSCRIBE IBMVM-L firstname lastname Send email text to: LISTSERV@VM. MARIST. EDU SUBSCRIBE CMS-PIPELINES firstname lastname Send email text to: LISTSERV@VM. MARIST. EDU SUBSCRIBE LINUX-390 firstname lastname See: this presentation’s “Notes” pages for details… 5

WHERE CAN I LOOK FOR HELP? Some REXX-specific documentation… The first two IBM documents explain REXX syntax – no reason to duplicate that here today. • z/VM: REXX/VM Reference 6. 4, SC 24 -6221 -02 http: //publibz. boulder. ibm. com/epubs/pdf/hcse 2 c 30. pdf • z/VM: REXX/VM User's Guide 6. 1 , SC 24 -6222 -01 http: //publibz. boulder. ibm. com/epubs/pdf/hcsb 3 c 30. pdf The document below includes examples, and some useful REXX coding styles, too. • REXX Language Coding Techniques (Tracy Dean) http: //www. vmworkshop. org/docs/2016 rlct. PDF (perhaps see the latest VM Workshop “yyyy” or “Previous Workshops” 6 pages for later updates)

BETTER PRACTICES: THE IMPORTANCE OF STANDARDS… • • • Improves productivity Improves clarity Provides automated “searchability” down the road • Huh? What else uses the same syntax, which might be wrong, or changing in a new release? Provides documentation RIGHT WHERE IT IS NEEDED (never out-of-date, and somewhere else – where it becomes obsolete without very strict update policies) • Someone else (or YOU) may need to adjust this later Enhances “transition management”. • Retirement happens, grey-hairs leave (or even face-plant into their keyboards). 7

BETTER PRACTICES: THE IMPORTANCE OF STANDARDS… DOCUMENTATION – DOCREXX EXEC T T-disk (filemode “T”) = “TOOLS disk” • A local convention: Contains common local and freeware tools available to Sysprogs, end-users, applications - no formal IBM or vendor support, but often supported by the previously mentioned IBMVM discussion list members. • • • See: ‘Free REXX-related Tools Sources’ later in this presentation T-disk is accessed AFTER the S and Y/S disks. IBM code has priority 8

BETTER PRACTICES: THE IMPORTANCE OF STANDARDS… DOCUMENTATION - DOCREXX EXEC T Prolog can be used to begin every EXEC • • EXEC filename/filetype • Who supports it • Maintenance level • This small amount of doc at the top display when tracing a flow of EXECs (e. g. ‘SET EXECTRAC ON”, or “trace i”, or “trace ? I”). There’s no need to wade through lots of detail at the top to get to the ‘good’ stuff every time you edit it. Epilog • • can be used to end every EXEC A bit more doc (adjust as needed), showing author, creation date, update history. Doesn’t intrude when running a trace. A good update log helps identify differences between multiple copies of the same EXEC. (It happens) 9

THE IMPORTANCE OF STANDARDS… DOCUMENTATION: DOCREXX EXEC T See the “Notes” pages in this presentation for extensive comments regarding “DOCREXX EXEC” /* Prolog; See Epilog for additional information @@@@@@@@@@ @ Exec Name EXEC @ @ Unit Support @ @ Status - Version n, Release n. n @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@*/ address 'COMMAND' parse source xos xct xfn xft xfm xcmd xenvir. parse upper arg parms 1 operands '(' options ')' parmrest hi='1 DE 8'x lo='1 D 60'x Signal ON Syntax Signal ON No. Value /* Signal ON ERROR */ If parms='? ' then Signal Explain /* 3270 Hilite Char /* 3270 Default Char */ */ . . . Place the body of your EXEC here. . . an example. . . parse var operands word 1 word 2. If word 1='A' & word 2='A' then Do say 'First arguments are identical. ' /* Say what's wrong */ Call Exit 20 '? ' /* Exit w/more help */ End Call Exit rc /*---------------------------------+ × Sub-Routines below this point × +---------------------------------*/ Exit: parse arg exitrc todo If todo='? ' then say 'For more help, enter: ' xfn '? ' If verify(exitrc, '-0123456789')>0 then Exit 999999 Exit exitrc 10

THE IMPORTANCE OF STANDARDS… DOCUMENTATION – DOCREXX EXEC T See the “Notes” pages in this presentation for additional details /* Prolog; See Epilog for additional information @@@@@@@@@@ @ Exec Name EXEC @ @ Unit Support @ @ Status - Version n, Release n. n @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@*/ address 'COMMAND' parse source xos xct xfn xft xfm xcmd xenvir. parse upper arg parms 1 operands '(' options ')' parmrest hi='1 DE 8'x lo='1 D 60'x Signal ON Syntax Signal ON No. Value /* Signal ON ERROR */ If parms='? ' then Signal Explain /* 3270 Hilite Char /* 3270 Default Char */ */ . . . Place the body of your EXEC here. . . an example. . . parse var operands word 1 word 2. If word 1='A' & word 2='A' then Do say 'First arguments are identical. ' /* Say what's wrong */ Call Exit 20 '? ' /* Exit w/more help */ End Call Exit rc /*---------------------------------+ × Sub-Routines below this point × +---------------------------------*/ Exit: parse arg exitrc todo If todo='? ' then say 'For more help, enter: ' xfn '? ' If verify(exitrc, '-0123456789')>0 then Exit 999999 Exit exitrc Use of “hi” and “lo” variables… say hi||’Nuclear core overheating! Abandon data center IMMEDIATELY!’lo’(No need to tell management)’ x. Nuclear core overheating!! Abandon data center IMMEDIATELY!x(No need to tell management) 11

THE IMPORTANCE OF STANDARDS… DOCUMENTATION – DOCREXX EXEC T Error: etxt. 1='+++ "ERROR: " error rtn entered in: ' xfn xft xfm', rc='rc etxt. 2='+++ from line: ' sigl', which reads: ' etxt. 3='+++'sourceline(sigl) cmdline=strip(sourceline(sigl), 'B') If symbol(value('CMDLINE'))='VAR' /* e. g cmd='CP FAIL'; cmd */ then cmdline=value('CMDLINE') ) else cmdline=value('CMDLINE') /* e. g. 'CP FAIL' */ etxt. 4='+++ which translates to: ' cmdline etxt. 0=4 'PIPE STEM etxt. × CONS' Call Exit 20 Syntax: etxt. 1='+++ "SYNTAX: " error rtn entered in: ' xfn xft xfm', rc='rc etxt. 2='+++ from line: ' sigl', which reads: ' etxt. 3='+++'sourceline(sigl) cmdline=strip(sourceline(sigl), 'B') cmdline=value('CMDLINE') etxt. 4='+++ which translates to: ' cmdline etxt. 0=4 'PIPE STEM etxt. × CONS' Call Exit 20 No. Value: etxt. 1='+++ "No. Value: " error rtn entered in: ' xfn xft xfm', rc='rc etxt. 2='+++ from line: ' sigl', which reads: ' etxt. 3='+++'sourceline(sigl) etxt. 4='+++ Variable with no value is: ' condition('Description') etxt. 0=4 'PIPE STEM etxt. × CONS' Call Exit 24 12

THE IMPORTANCE OF STANDARDS… DOCUMENTATION – DOCREXX EXEC T Explain: 'PIPE (NAME Explain)' , '× <' xfn xft xfm , '× INSIDE /Explain. Begin: / /Explain. End: /' , '× PREFACE STRLITERAL /'xfn xft xfm 'help. . . /' , '× CONSOLE' Call Exit 0 /* Explain. Begin: ===> Place command description and syntax here, between ===> lines beginning with "Explain. Begin: " and "Explain. End: " ===> A sample "railroad-style" syntax is shown below. +-default operands--+ >>-Cmdname--+-------------------+-------->< +-optional operands-+ +-(-× Options ×-+---+ +-)-+ ×-Options-× Explain. End: */ 13

THE IMPORTANCE OF STANDARDS… DOCUMENTATION – DOCREXX EXEC T /* Epilog @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ Component of @ @ Called by @ @ Dependencies - VM/SP 3 or higher. @ @ - e. g. LISTFILE, COPYFILE, etc. @ @ Program Lang. - CMS REXX @ @ Return Codes - 0, Successful completion @ @ 4, Help requested, or no operands entered. @ @ 8, Command operands not entered properly, failed. @ @ 12, Unexpected condition found, failed. @ @ 20, Internal logic error in command, failed. @ @ Date Written - yyyymmdd @ @ Author - First M. Last @ @ Changed @ By @ Description of Change @ @ ----+--------------------------- @ @ yyyymmdd iii @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@*/ 14

BETTER PRACTICES: REXX FILE FORMATTING STANDARDS (RELIGION) Without typical language structure, REXX syntax and formatting often inspires near-religious debate Be extravagant with comments when writing code. They will help you when you get old, grey-haired, and forget the code after a “long time”. If you’re like me, they’ll help you next week. That said, there is such a thing as too many comments: ‘’ERASE SOME FILE A’ /* Erase the file */ Try to place comments where they explain something that’s not obvious, could have multiple meanings, is based upon the results (e. g expected responses) of commands, etc. 15

BEST PRACTICES: REXX FORMATTING (RELIGION) In REXX code: I tend to line up ‘SELECT/DO/END’ clauses, helping find missing or extra END statements in XEDIT (what a GREAT editor!): If ? Almost. Done then Do until ? All. Done …many statements… End /* until ? All. Done */ ALL / SELECT / | / DO / | / END / Do until ? All. Done ---------- dozens of line(s) not displayed ---------End /* until ? All. Done */ ---------- bazillions of line(s) not displayed -------- 16

BETTER PRACTICES: REXX FORMATTING (RELIGION) I like Boolean variables (i. e. those TRUE (1), or FALSE (0) flags) to begin with ‘? ’. E. g. “If ? found then …” Once they notice the pattern, it helps next reader understand that the variable should only be true or false. I causes a circumventable problem with the default CMS Pipelines “ENDCHAR” (‘? ’). IMHO … avoid use of the ‘INTERPRET’ statement if at all possible (very powerful, very confusing – especially months later). 17

BETTER PRACTICES: REXX FORMATTING (FACTS) Avoid use of the IBM “Logical Not” symbol “ ¬ ”, instead use “<>”, or “” … as in “? true” Why? Other operating systems support REXX of some flavor (e. g. Regina REXX), but do not always understand IBM’s “Logical Not” Always type FULL COMMANDS, not Abbreviations or Aliases into EXECs (and XEDIT macro files, and filetype “REXX” CMS Pipelines) files. • A user may have their own abbreviations and aliases • With the FULL COMMAND you can scan code to find out where a command is used. • REXX interpretation runs faster without abbreviations. 18

THE IMPORTANCE OF STANDARDS – BULLET-PROOFING YOUR CODE BEST PRACTICE: ALWAYS begin EXECs with: address ‘COMMAND’ (or: address COMMAND) Ø COMMAND is a REXX ‘reserved word’; thus, it does not need to be within quotes. Ø address ‘COMMAND’ establishes the COMMAND “environment”; it keeps your code from running (e. g. ) any ‘ACCESS EXEC’, or ‘QUERY EXEC’ that someone has accessed. To run them from the ‘COMMAND’ environment your code will requite your to execute ‘EXEC ACCESS whatever’, or ‘EXEC QUERY whatever’. It’s not too hard to get used to writing this way, and it VASTLY reduces diagnostic time when users call for help. Ignore this, and it WILL bite you when you least expect it. Even if you ignore everything else in this presentation, PLEASE FOLLOW THIS RECOMMENDATION!!! 19

FREE REXX-RELATED TOOLS SOURCES • IBM VM Download page - http: //www. vm. ibm. com/download/ • VM Workshop tools pages - http: //www. vmworkshop. org/tools. shtml (drill down for my donations under: Developer Pages > Mike Walter) • Explore all the links under the VM Workshop Tools page, it’s worth the time. Take advantage of someone else’s “round wheel” instead of creating your own, and learn their REXX coding techniques, too! • See also Dave Jones’ “IPGATE” - http: //www. vmworkshop. org/DJIPGATE. shtml • Sine Nomine Associates (SNA), some chargeable http: //www. sinenomine. net/vm/products • CMS-Pipelines Runtime Library - http: //vm. marist. edu/~pipeline/ • John Hartmann (AKA: the “the Piper”, CMS-Pipelines’ author) provided ongoing CMS-Pipelines Runtime Library (RTL) fixes and major functional enhancements to the RTL - far beyond what was provided prior to z/VM 6. 4. Much to the distress of z/VM customers the VM Development Lab’s “Endicott Pipes” (often referred to as “iron pipes”) distributed with z/VM through 6. 3 was pretty much functionally stabilized, . In preparation for z/VM 6. 4, IBM assigned master plumber Rob van der Heij to update the CMS Pipelines distributed with z/VM 6. 4 with as much of the RTL as possible. <insert loud relieved sigh here> 20

FREE REXX-RELATED TOOLS QDI EXEC QDI, John Hartmann's XEDIT Macro for Coloring Program Syntax Elements http: //vm. marist. edu/~pipeline/#QDI 21

FREE REXX-RELATED TOOLS CKRX EXEC Why wait until an EXEC is placed into production to find simply REXX syntax errors? • • Good: Trace S (Syntax) • Internal, built-into REXX. Performs a full syntax check without executing. • I can’t begin the number of times I added a “trace s’, fixed all the reported errors, and then copied that perfect EXEC to a production disk, without removing the ‘trace s’! <sigh> Better: CKRX EXEC • CKRX is part of REXXG (Rexx Goodies): http: //www. vm. ibm. com/download/packages/descript. cgi? REXXG 22

MISCELLANY FROM : TRACY DEAN Some material appropriated from: REXX Language Coding Techniques (Tracy Dean) http: //www. vmworkshop. org/docs/2016 rlct. PDF 23

MISCELLANY FROM: TRACY DEAN 24

MISCELLANY REXX FUNCTION CALLS CAN EAT CPU String=‘Here are some words to be parsed. ’ Char 1=left(string, 1) parse var string Char 1 2 /* “left” uses more CPU time than “parse” */. /* Strange, but true */ PARSE is very, very powerful, and very fast. Does it matter any more – with fast CPUs, and few large CMS applications written in REXX? It may if you have a complex looping REXX-based utility called automatically, and which must respond quickly (think: web-apps). Nonetheless, PARSE is still very powerful. Once understood it can save you significant coding time. 25

FREE REXX-RELATED TOOLS MKSALIPL EXEC So what does an exec following these examples look like? The following MKSALIPL (Make Stand. ALone IPLer) EXEC is pretty old (from 2000 -11 -17), has some old/obsolete DOCREXXX EXEC template standards, but the indentation style still helps one to quickly follow the code, locate sub-routines, and see the functional syntax without referring to an external “MKSALIPL HELPCMS” file. 26

/* Prolog; See Epilog for additional information ********** * Exec Name - MKSALIPL EXEC * * Unit Support - OSS/VM * * Status - Version 1, Release 1. 0 * **********************************/ address 'COMMAND' parse source xos xct xfn xft xfm xcmd xenvir. parse upper arg parms 1 operands '(' options ')' parmrest Signal ON Syntax Signal ON No. Value /* Signal ON ERROR */ hi='1 DE 8'x lo='1 D 60'x parse var operands writevdev volid. If writevdev='? ' then Signal Explain /* 3270 Hilite Char /* 3270 Default Char */ */ If writevdev='' then writevdev='0 F 00' /* Where to write SALIPL */ extent=1 /* Which CP-fmt'd "PARM" extent from which */ /* the "CPLOAD MODULE" should be loaded */ minivol='NOVERIFY' /* Do not verify rdev/mdisk volser label */ module='CPLOAD' /* Default=CPLOAD, CP nucleus module to load*/ offset=0 /* Default=0, must be 0 if "extent" is given*/ origin=1000 /* Default=1000, address at which SALIPL */ /* should load the "module". */ If volid='' then volid='NOVERIFY' iplparms='' /* Volser to be checked before SALIPL is /* written to that disk. /* Typically entered at IPL time */ */ */ comments='? ' /* Exactly 4 lines of comments, truncated at 80 bytes */ c. 1='Some possible IPL PARAMETERS section (above) entries: ' c. 2='CONS=ccuu PROMPT <--- Used most often' c. 3='NOEXITS FN=system FT=config' c. 4='PDNUM=Parm. Disk. Num PDVOL=Parm. Disk. Volser PDOFF=Parm. Diskcyl. Offset' c. 0=4 27

cmd='SALIPL' writevdev '(EXTENT' extent 'MINIVOL' minivol , 'MODULE' module 'ORIGIN' origin 'VOLID' volid , 'COMMENTS' comments Do forever say hi say 'The following command is about to be executed' say lo say cmd say 'stacked Comments: ' 'PIPE STEM c. | CONS' say hi say 'Continue? Enter Yes or No' say lo parse upper pull ans. If abbrev('YES', ans, 1) then Leave /* Forever */ If ans='NO' | ans='N' then Do say 'Aborting before writing SALIPL per reply: ' ans Call Exit 32 End say '+++ Invalid reply: ' ans End 'PIPE STEM c. | STACK' cmd Call Exit rc Explain: say xfn 'is used to write SALIPL to the a given address (usually a' say 'full-pack extent minidisk. ' say ' +-0 F 00 -+--+-NOVERIFY-+ ' say '>-MKSALIPL--+-vdev-+--+-volser---+--><' say Call Exit 4 /**********************************/ /* Sub-Routines below this point */ /**********************************/ 28

Exit: parse arg exitrc. If verify(exitrc, '-0123456789')=0 then Exit exitrc else Exit 999999 Syntax: say '+++ Syntax error routine entered in: ' xfn xft xfm say '+++ from line: ' sigl', which reads: ' say '+++'sourceline(sigl) Call Exit 20 No. Value: say '+++ No. Value error routine entered in: ' xfn xft xfm say '+++ from line: ' sigl', which reads: ' say '+++'sourceline(sigl) Call Exit 24 /* Epilog ****************************** * Function - See 'EXPLAIN' subrtn above. * * Component of - VM Sysprogs toolbox * * Command format- See 'Explain; subrtn above. * * Called by - VM sysprogs * * Program Lang. - CMS REXX * * Date Written - 20001117 * * Author - Michael R. Walter * * Acknowlegments- Based upon code the to the VMESA-L listserv * * Thu, 31 Aug 2000 13: 35: 14 -0500 * * "Frank M. Ramaekers Jr. " <Frank. Ram@Earthlink. Net>* * Changed | By | Description of Change * * ----+--------------------------- * * yyyymmdd iii * ***********************************/ 29