Routine Documentation

Each routine should contain a star box that looks like the following:

**********************************************************************
*
* NAME:       For the first routine (MAIN) this should be your name.
*
*             For all other routines, this should be the name of the
*             routine, usually the first label in the routine, that the
*             caller references (i.e. a CSECT label for external routines)
*
* FUNCTION:   This should be a one or more line description of what 
*             the routine is supposed to do.
*
* INPUT:      This is a description of the physical data that is read 
*             by the routine. A routine ONLY has input if it contains 
*             an XREAD command. If there is no input, specify ‘NONE’.
*
* OUTPUT:     This is a description of any information sent to the 
*             printer, such as reports. A routine ONLY has output if 
*             it contains an XDUMP or XPRNT command. If there is no
*             output, specify ‘NONE’.
*
* ENTRY CONDS: This stands for Entry Conditions. This should describe 
*              the parameters passed to the routine. If there are no 
*              parameters passed, specify ‘NONE’. An example of 
*              possible list:
*
*              0(1) -- address of the beginning of the table
*              4(1) -- address of the input buffer
*
* EXIT CONDS:  This stands for Exit Conditions. This should represent 
*              what registers the routine will purposely change before 
*              returning back to the calling routine. If there are no 
*              register exit conditions, specify ‘NONE’. For example:
*
*              R15 -- return code (0 = success, 4 = failure)
*
* REGISTER USAGE: This should describe what registers are being used 
*                 in the routine and what they are used for. For 
*                 example:
*
*                 R6 -- address of the table
*                 R15 -- base register
*
* PSEUDOCODE:  This should be a generic description of what logic was 
*              used to write the routine. For example:
*
*              <1> Initialize the counters
*              <2> Read the first record
*              <3> While it is not end of file
*                     Display the record
*              <4>    If the number is positive
*                       Add number to positive sum
*                     Else
*                       Add number to negative sum
*                     Endif
*              <5>    Read the next record
*                  Endwhile
*              <6> Print the counters
*
* NOTES:      This should specify any special programming techniques 
*             that are used in the routine. For example, special 
*             formulas or assumptions that are being made. If there is 
*             nothing to be specified, it may be omitted.
**********************************************************************

In some cases, not all of this is necessary. In all cases, you should list the name, function and register usage.

You can find more descriptions and examples in the Course Notes book.

Some Extras

TITLE "a suitable title for the page goes here"

• TITLE begins in column 10

• The value between ‘ ’ will be displayed at the top of each new page.

SPACE n

• SPACE begins in column 10

• This leaves n blank lines in the source code listing.

• n defaults to 1

EJECT

• EJECT begins in column 10

• This advances the source code to a new page.

NOTE: Don't go overboard with your use of SPACE and EJECT in a program!!!