Using OPS/REXX › How to Implement Common Coding Guidelines

How to Implement Common Coding Guidelines

The REXX programming language coupled with many of the CA OPS/MVS Host Environments and functions let you create effective and efficient automated applications. When creating your AOF rules and OPS/REXX programs, you should establish common coding guidelines (upper or lower case,comment blocks,number of spaces to indent,and so on).

To begin implementing common coding standards within CA OPS/MVS automated applications, review the following coding guidelines:

1. Design a template to be used as a beginning comment block within all programs and rules.

   Include informative data fields such as purpose, related programs rules, logic outline, and so on.

   The following is an example beginning comment block template:

   /**********************************************************************/
   /*   Name       - Rule_or_pgm_name                                    */
   /*   Purpose    - Brief sentence or two to identify what this AOF     */
   /*                rule or OPS/REXX program accomplishes.              */
   /*   Related    - List any other related rules pgms here.Include      */
   /*                ruleset name if an AOF rule is related,and complete */
   /*                PDS name if an OPS/REXX pgm. Such as:               */
   /*                          TOD.CICSSHUT                              */
   /*                          SYS2.OPSMVS.USER.REXX(CICSSHUT)           */
   /*   Globals    - List any GLOBAL,GLVTEMP,or GLVJOBID variables       */
   /*                being used within program. Such as:                 */
   /*                GLVTEMP1.PRIMARY.MUF - Contains system of the       */
   /*                                       primary CA Datacom/AD        */
   /*                                       MUF system                   */
   /*                GLVTEMP1.PRODFAIL.jobname - Contains failure info   */
   /*                                            of the specific jobname */
   /*                                                                    */
   /*   History    - 25 OCT 2010 DAG  - Original implementation          */
   /*                22 JAN 2010 DAG  - Added logic to ................  */
   /*                                   ...............................  */
   /*   Notes      - This section would list detailed information of     */
   /*                of this rule or program. Begin with more details    */
   /*                of why the automation is needed. List an overview   */
   /*                of the logic in an 1-x format. Such as:             */
   /*                                                                    */
   /*                Outline of the logic flow :                         */
   /*                1. ABENDLOG AOF rule processes the triggering       */
   /*                   IEF450I event and inserts desired event data     */
   /*                   into a RDF table created within rule.            */
   /*                2. A dynamic TOD rule created within the ABENDLOG   */
   /*                   AOF rule will trigger this OPS/REXX program.     */
   /*                3. Logic in this program will simply read the data  */
   /*                   stored in the RDF table, and write to some       */
   /*                   preallocated sequential data set.                */
   /*                                   .                                */
   /*                                   .                                */
   /**********************************************************************/
   

2. Create uniform comment blocks to be used before the instructions and logic.

   Adhere to the following conventions:

   • Add a number line as last comment line to assist when indenting for wrap around lines or specific instructions such a DO...END.
   • Use mixed case in your comment descriptions.
   • Optionally, comment the block sections of a program, such as:
     • Main processing
     • Sub-routines

   Example comment block used before instructions or logic:

   /*--------------------------------------------------------------------*/
   /* Uniform comment block to be placed prior to specific logic or      */
   /* instructions .......................                               */
   /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7*/
   
   /*--------------------------------------------------------------------*/
   /*--------------------- Internal sub-routines ------------------------*/
   /*--------------------------------------------------------------------*/
                                                                           
   /*--------------------------------------------------------------------*/
   /* subroutine name:                                                   */
   /*  -Brief description of work performed in this subroutine......     */
   /*--+----1----+----2----+----3----+----4----+----5----+----6----+----7*/
   

3. Create meaningful names for the variables based on the data that they will be assigned.

   Simple variables will be used widely across all your rules and programs. The more descriptive the names, the easier it will be to maintain the code.

4. Use upper and lower case consistently to create variable names.

   Various supplied CA OPS/MVS samples use lower case for simple variable names. For example:

   cicsregion   = msg.jobname 
   abendcode    = WORD(msg.text,4) 
   prod_systems = 'SYSA SYSB SYSC' 
   

   Adhere to the following case conventions:

   • Choose to upper case CA OPS/MVS reserved stemmed variable names GLVJOBID, GLOBAL,or GLVTEMP.

     For example:

     cics_regions = OPSVALUE('GLOBAL1.CICSREGIONS','O') 
     

     payroll_contacts = OPSVALUE('GLOBAL1.PAYROLL.CONTACTS','O') 
     

   • If part of the stemmed variable name is that of a defined simple variable, then use the same case for the variable as it was originally created.
   • Create clean coding of the OPSVALUE() by assigning the variable name and value to be updated to a simple variable that will act as a staging variable.

     For example:

     cicsregion = msg.jobname 
     varname    = 'GLVTEMP1.'cicsregion'.SHUTDOWN' 
     setvar     = OPSVALUE(varname,'U','REQUESTED')
     
     smfid     = OPSINFO('SMFID')
     ipldate   = OPSINFO('IPLDATE')
     ipltime   = OPSINFO('IPLTIME')
     iplvolser = OPSINFO('IPLVOLSER')
     iplinfo   = ipldate ipltime iplvolser
     ipl_varname = 'GLVTEMP1.IPLINFO.'smfid
     setvar      = OPSVALUE(ipl_varname,'U',iplinfo)
     

5. Pick your case standard for coding OPS/REXX and TSO/E REXX functions.

   Authors of CA OPS/MVS samples uppercase all function names and optional or required arguments. If a variable name is used within a function argument, then use the same case that it was created in, for example:

   inits  = OPSJES2('I','INIT','*','A') 
   isitactive = OPSTATUS('A','I',jobname) 
   device = WORD(SUBSTR(record,device_loc),1) 
   smfid = OPSINFO('SMFID') 
   

6. Establish case guidelines for host environment commands, both CA OPS/MVS host environments and other host commands.

   Mixed case is mainly used within many of the CA OPS/MVS samples when coding the keywords of the host environments, with the exception of the the SQL host environment,where uppercase is used for table and column names.

   For example:

   address WTO
   "Msgid(OPSNOTIFY) Text('Payroll schedule is late')", 
      "Desc(1) Route(1)" 
   
   address OPER
   "Command(D GRS,ANALYSE,BLOCKER) Nooutput"
   
   address SQL
   "Update STCTBL set DESIRED_STATE = 'DOWN' where", 
      "TYPE = 'TESTCICS'"
   
   address OPER
   "Command(DB1ADIS DB(DB2CA11) LIMIT(*) LOCKS)",
     "Cmdwait(30) Stopresp(DSN9022I) Interval(0) Stopend(NO)" 
   

7. For OPS/REXX or REXX instruction, establish consistent case style, indenting, and commenting using the following guidelines:
   • Choose either upper case or lower case as follows:
     • if..then..else or If..Then..Else
     • do..end or Do..End
     • select..when..otherwise or Select..When...Otherwise
     • parse var msgtxt or Parse Var msgtxt
   • Be consistent in the number of spaces you indent to begin instruction.
     • To begin instruction, use the same number of spaces to indent your do...end instructions.
     • Use the same number of spaces to indent each instruction within the loop. (such as two spaces).
   • Line up the end instruction with the associating do instruction. This is especially helpful within nested the do...end loops.
   • Place a comment with the end instruction to identify what loop is ending.

     This coding aid assists in the maintenance of your programs.

   Note: The same rules apply when coding the select..when..otherwise instruction.

   Example:

   select 
     when commands = 'HELP'    then call help /*Ident when 2 spaces*/
     when commands = 'IPL'     then call ipl  /*Line up all when's */
     when commands = 'JACT'    then call jact
     when commands = 'JSPOOL'  then call jspool
     when commands = 'WTORS'   then call wtors
     when commands = ''        then call help
   otherwise Nop                            /*Line up with 'select'*/
   end                                      /*Line up with 'select'*/
   
   do i = 1 to total_msfnames          /* Loop through all abends  */
     pull msfedq                       /* Get msf record from EDQ  */
     allmsfs = allmsfs + 1             /* Up counter of all msfs   */
     msfname.allmsfs = WORD(msfedq,2)  /* Set stemmed msf variable */
   end                                 /* End of loop for all MSFs */