ASSEMBLER DOCUMENTATION STANDARDS
    

The following standards apply to CSCI 465 Assembler programs.
    
1.  Line Documentation:
   
   --- At least 95 percent of the instruction statements should contain 
       documentation.  Comments may begin following at least one blank 
       after the instruction's operand(s) and through column 71.  Explain 
       what the instruction is doing and how it affects any variables or 
       registers.

   --- Other comments as needed using an '*' in column 1.

   --- Use line documentation in storage areas as well.

2.  A block of comments outlined with a box of asterisks, referred to
    as the 'DOC BOX', should precede each CSECT and should contain the
    following:

    --- One sentence stating the function of the routine.

    --- Descriptions of the input and output including DDNAMES.

    --- Entry and exit conditions (parameters, return codes, etc.)

    --- Notes concerning any inherent limitations, tricky code, etc.
        If there are no notes, state 'NOTES:  None.' in the DOC BOX.
    
    --- Pseudocode of the routine's logic.  Number key steps in the 
        pseudocode and place a numbered comment line within the
        routine code corresponding to the logical step.  Use no more 
        than fifteen steps.

3.  To improve the readability of the program listing, utilize the
    following Assembler instructions:
    
   --- TITLE -- create an appropriate heading at the top of each page in 
       the listing for each macro definition, dummy section, control 
       section or routine.  Include the name of the section of code.

   --- EJECT -- separate routine modules with a page advance.  Avoid 
       distracting automatic page breaks, i.e. in the middle of 
       complicated logic.  Force a page advance before the routine begins.

   --- SPACE -- insert blank lines to separate portions of logic within a 
       routine.  Group lines of code logically.



ASSEMBLER Control Section Documentation Example:


******************************************************************
*                                                                *
*  FUNCTION:  THIS ROUTINE LISTS THE NAMES OF THOSE STUDENTS     *
*             WHO ARE BOTH COMPUTER SCIENCE AND MATHEMATICS      *
*             MAJORS.                                            *
*                                                                *
*  INPUT:     NONE.                                              *
*                                                                *
*  OUTPUT:    A PRINTED REPORT.                                  *
*                                                                *
*  ENTRY CONDITIONS:  R1 HOLDS THE ADDRESS OF A PARAMETER LIST.  *
*                                                                *
*              0(R1) - ADDRESS OF TABLE 1 ( COMP SCI MAJORS )    *
*              4(R1) - ENDING ADDRESS OF TABLE 1                 *
*              8(R1) - ADDRESS OF TABLE 2 ( MATH MAJORS )        *
*             10(R1) - ENDING ADDRESS OF TABLE 2                 *
*             12(R1) - TOTAL NUMBER OF COMP SCI - MATH MAJORS    *
*                      (TO BE ACCUMULATED)                        *
*                                                                *
*  EXIT CONDITIONS:  R1 RETURNS THE ADDRESS OF SAME PARAMETER    *
*                    LIST WITH 12(R1) UPDATED WITH TOTAL NUMBER  *
*                    OF COMP SCI - MATH MAJORS.                  *
*                                                                *
*  NOTES:   None                                                 *
*                                                                *
*                                                                *
*  ALGORITHM:                                                    *
*                                                                *
*  1.  INITIALIZE TABLE POINTERS.                                *
*      INITIALIZE ACCUMULATOR TO ZERO.                           *
*  2.  DO WHILE (NOT END OF TABLE 1)                             *
*        GET TABLE 1 STUDENT SSN                                 *
*  3.    DO WHILE (NOT END OF TABLE 2)                           *
*             AND (MATCH NOT FOUND)                              *
*           GET TABLE 2 STUDENT SSN                              *
*  4.       IF SSN 1 = SSN 2                                     *
*              INCREMENT ACCUMULATOR                             *
*              PRINT STUDENT NAME AND SSN                        *
*           ENDIF                                                *
*  5.       INCREMENT TABLE 2 POINTER                            *
*        ENDDO                                                   *
*  6.    INCREMENT TABLE 1 POINTER                               *
*      ENDDO.                                                    *
*  7.  RETURN ACCUMULATOR VALUE IN PARAMETER LIST.               * 
*      EXIT.                                                     *
*                                                                *
******************************************************************



ASSEMBLER Line Documentation Example:
    

         TITLE 'LINE DOCUMENTATION EXAMPLE'    
LINKAGE  CSECT
         PRINT NOGEN            DO NOT EXPAND MACROS
         EQUREGS                GENERATE REGISTER EQUATES
         SPACE 2                GIVE ME TWO BLANK LINES
         STM   R14,R12,12(R13)  SAVE REGS IN CALLER'S SAVE AREA
         LR    R12,R15          COPY CSECT ADDRESS INTO R12
         USING LINKAGE,R12      ESTABLISH R12 AS THE BASE REG
*                                 WITH THIS CSECT AS THE BASE
*                                 ADDRESS
         LA    R14,SAVEAREA     R14 POINTS TO THIS CSECT's SAVE
*                                 AREA
         ST   R14,8(R13)        STORE ADDRESS OF THIS CSECT's
*                                 SAVE AREA (FORWARD LINKAGE)
*                                 IN CALLER'S SAVE AREA
         ST   R13,4(R14)        STORE ADDRESS OF CALLER'S SAVE
*                                 AREA IN THIS CSECT's SAVE AREA
*                                 (BACKWARD LINKAGE)
         LR   R13,R14           POINT R13 AT THIS CSECT'S SAVE
*                                 AREA
.
         .
         .

ENDPGM   SR    R15,R15          R15 = RETURN CODE OF 0
         L     R13,4(R13)       POINT R13 TO CALLER'S REGS
*                                 IN THIS CSECT's SAVE AREA
         L     R14,12(R13)      RESTORE REGISTER 14
         LM    R0,R12,20(R13)   RESTORE R0 THRU R12
*                                 DO NOT RESTORE R15 SINCE IT
*                                 CONTAINS THE RETURN CODE
         BR    R14              BRANCH TO CALLER'S NEXT
*                                 INSTRUCTION
         EJECT                  SKIP TO TOP OF NEXT PAGE
*                                 IN LISTING
         LTORG
SAVEAREA DS    18F              SAVE AREA RESERVED FOR ANOTHER
*                                 CSECT TO SAVE REGS IF CALLED
    

(NOTE: For a more detailed explanation of standard linkage see Grauer, 
The IBM COBOL Environment, "Linkage Conventions")