Seq # *Modification Id* Act
----------------------------+
00001 M01S00001.coding +++|*NOSEQ
00002 M01S00002.coding +++|*WIDTH 132
00003 M01S00003.coding +++|1 PAGE 1
00004 M01S00004.coding +++|
00005 M01S00005.coding +++|
00006 M01S00006.coding +++|
00007 M01S00007.coding +++|
00008 M01S00008.coding +++|
00009 M01S00009.coding +++|
00010 M01S00010.coding +++|
00011 M01S00011.coding +++|
00012 M01S00012.coding +++|
00013 M01S00013.coding +++|
00014 M01S00014.coding +++|
00015 M01S00015.coding +++|
00016 M01S00016.coding +++|
00017 M01S00017.coding +++|
00018 M01S00018.coding +++|
00019 M01S00019.coding +++| ------------------------------------------------------------
00020 M01S00020.coding +++| ! !
00021 M01S00021.coding +++| ! NOS COMPASS PROGRAMMING STANDARD !
00022 M01S00022.coding +++| ! !
00023 M01S00023.coding +++| ------------------------------------------------------------
00024 M01S00024.coding +++|
00025 M01S00025.coding +++|
00026 M01S00026.coding +++|
00027 M01S00027.coding +++|
00028 M01S00028.coding +++|
00029 M01S00029.coding +++|
00030 M01S00030.coding +++|
00031 M01S00031.coding +++|
00032 M01S00032.coding +++|
00033 M01S00033.coding +++|
00034 M01S00034.coding +++|
00035 M01S00035.coding +++|
00036 M01S00036.coding +++|
00037 M01S00037.coding +++|
00038 M01S00038.coding +++|
00039 M01S00039.coding +++|1 PAGE 2
00040 M01S00040.coding +++|
00041 M01S00041.coding +++|
00042 M01S00042.coding +++| TABLE OF CONTENTS
00043 M01S00043.coding +++|
00044 M01S00044.coding +++|
00045 M01S00045.coding +++| 1.0 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 6
00046 M01S00046.coding +++| 1.1 SCOPE OF DOCUMENT . . . . . . . . . . . . . . . . . . . 6
00047 M01S00047.coding +++| 1.1.1 PURPOSE . . . . . . . . . . . . . . . . . . . . . . 6
00048 M01S00048.coding +++| 1.1.2 SCOPE OF USE . . . . . . . . . . . . . . . . . . . 6
00049 M01S00049.coding +++| 1.2 CONFORMANCE AND ENFORCEMENT . . . . . . . . . . . . . . 6
00050 M01S00050.coding +++|
00051 M01S00051.coding +++| 2.0 DOCUMENTATION . . . . . . . . . . . . . . . . . . . . . 7
00052 M01S00052.coding +++| 2.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 7
00053 M01S00053.coding +++| 2.1.1 DESIGN OVERVIEW . . . . . . . . . . . . . . . . . . 7
00054 M01S00054.coding +++| 2.1.2 EXTERNAL INTERFACE . . . . . . . . . . . . . . . . 7
00055 M01S00055.coding +++| 2.1.3 INTERNAL OPERATION . . . . . . . . . . . . . . . . 8
00056 M01S00056.coding +++| 2.1.4 DETAILED CODE ANALYSIS . . . . . . . . . . . . . . 8
00057 M01S00057.coding +++| 2.2 GENERAL REQUIREMENTS . . . . . . . . . . . . . . . . . 9
00058 M01S00058.coding +++| 2.2.1 ABBREVIATIONS . . . . . . . . . . . . . . . . . . . 9
00059 M01S00059.coding +++| 2.2.2 PUNCTUATION . . . . . . . . . . . . . . . . . . . . 9
00060 M01S00060.coding +++| 2.2.3 FORMATS . . . . . . . . . . . . . . . . . . . . . . 10
00061 M01S00061.coding +++| 2.2.4 FORMAT OF ITEMIZED DOCUMENTATION . . . . . . . . . 11
00062 M01S00062.coding +++| 2.3 PROGRAM LEVEL DOCUMENTATION . . . . . . . . . . . . . . 11
00063 M01S00063.coding +++| 2.3.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 11
00064 M01S00064.coding +++| 2.3.2 EXTERNAL . . . . . . . . . . . . . . . . . . . . . 12
00065 M01S00065.coding +++| 2.3.3 INTERNAL . . . . . . . . . . . . . . . . . . . . . 12
00066 M01S00066.coding +++| 2.4 SUBROUTINE LEVEL DOCUMENTATION . . . . . . . . . . . . 13
00067 M01S00067.coding +++| 2.4.1 ENTRY CONDITIONS (ENTRY) . . . . . . . . . . . . . 14
00068 M01S00068.coding +++| 2.4.2 EXIT CONDITIONS (EXIT) . . . . . . . . . . . . . . 14
00069 M01S00069.coding +++| 2.4.3 ERROR EXIT CONDITIONS (ERROR) . . . . . . . . . . . 14
00070 M01S00070.coding +++| 2.4.4 REGISTER OR DIRECT CELL USAGE (USES) . . . . . . . 15
00071 M01S00071.coding +++| 2.4.5 ROUTINES CALLED (CALLS) . . . . . . . . . . . . . . 16
00072 M01S00072.coding +++| 2.4.6 COMMON OR SYSTEM DECKS REQUIRED (XREF) . . . . . . 16
00073 M01S00073.coding +++| 2.4.7 MACROS CALLED (MACROS) . . . . . . . . . . . . . . 16
00074 M01S00074.coding +++| 2.4.8 ALLOCATED REGISTERS OR DIRECT CELLS (DEFINE) . . . 16
00075 M01S00075.coding +++| 2.4.9 TIMING CONSIDERATIONS (TIMING) . . . . . . . . . . 16
00076 M01S00076.coding +++| 2.4.10 PROGRAMMING NOTES (NOTES). . . . . . . . . . . . . 16
00077 M01S00077.coding +++| 2.5 CODE LEVEL DOCUMENTATION . . . . . . . . . . . . . . . 17
00078 M01S00078.coding +++| 2.5.1 STAND-ALONE COMMENTS . . . . . . . . . . . . . . . 17
00079 M01S00079.coding +++| 2.5.2 EMBEDDED COMMENTS . . . . . . . . . . . . . . . . . 17
00080 M01S00080.coding +++| 2.6 MACRO LEVEL DOCUMENTATION . . . . . . . . . . . . . . . 18
00081 M01S00081.coding +++| 2.6.1 ENTRY CONDITIONS (ENTRY) . . . . . . . . . . . . . 19
00082 M01S00082.coding +++| 2.6.2 EXIT CONDITIONS (EXIT) . . . . . . . . . . . . . . 19
00083 M01S00083.coding +++| 2.6.3 REGISTER OR DIRECT CELL USAGE (USES) . . . . . . . 20
00084 M01S00084.coding +++| 2.6.4 ROUTINES CALLED (CALLED) . . . . . . . . . . . . . 20
00085 M01S00085.coding +++| 2.6.5 MACROS CALLED (MACROS) . . . . . . . . . . . . . . 20
00086 M01S00086.coding +++| 2.7 DOCUMENTATION EXAMPLES . . . . . . . . . . . . . . . . 20
00087 M01S00087.coding +++| 2.7.1 PROGRAM LEVEL . . . . . . . . . . . . . . . . . . . 20
00088 M01S00088.coding +++| 2.7.2 SUBROUTINE LEVEL (PP CODE) . . . . . . . . . . . . 21
00089 M01S00089.coding +++| 2.7.3 SUBROUTINE LEVEL (CP CODE) . . . . . . . . . . . . 22
00090 M01S00090.coding +++| 2.7.4 MACRO LEVEL DOCUMENTATION . . . . . . . . . . . . . 23
00091 M01S00091.coding +++|
00092 M01S00092.coding +++|1 PAGE 3
00093 M01S00093.coding +++|
00094 M01S00094.coding +++|
00095 M01S00095.coding +++| 3.0 CODING . . . . . . . . . . . . . . . . . . . . . . . . 24
00096 M01S00096.coding +++| 3.1 CARD/LINE LAYOUTS . . . . . . . . . . . . . . . . . . . 24
00097 M01S00097.coding +++| 3.1.1 COMPASS OPERATION CARDS . . . . . . . . . . . . . . 24
00098 M01S00098.coding +++| 3.1.2 COMPASS COMMENT CARDS . . . . . . . . . . . . . . . 24
00099 M01S00099.coding +++| 3.2 PROGRAM LAYOUT . . . . . . . . . . . . . . . . . . . . 24
00100 M01S00100.coding +++| 3.2.1 GROUP 1 INSTRUCTIONS . . . . . . . . . . . . . . . 25
00101 M01S00101.coding +++| 3.2.1.1 PERIPHERAL PROCESSOR PROGRAMS . . . . . . . . . . 25
00102 M01S00102.coding +++| 3.2.1.2 CENTRAL PROCESSOR PROGRAMS . . . . . . . . . . . 25
00103 M01S00103.coding +++| 3.2.1.3 COMMON DECKS . . . . . . . . . . . . . . . . . . 26
00104 M01S00104.coding +++| 3.2.2 PROGRAM LEVEL DOCUMENTATION . . . . . . . . . . . . 26
00105 M01S00105.coding +++| 3.2.3 MACRO DEFINITIONS . . . . . . . . . . . . . . . . . 26
00106 M01S00106.coding +++| 3.2.4 INSTALLATION SYMBOL DEFINITIONS . . . . . . . . . . 26
00107 M01S00107.coding +++| 3.2.5 LOCAL SYMBOL DEFINITIONS . . . . . . . . . . . . . 26
00108 M01S00108.coding +++| 3.2.6 GLOBAL MEMORY DEFINITIONS . . . . . . . . . . . . . 27
00109 M01S00109.coding +++| 3.2.7 MAIN LOOP . . . . . . . . . . . . . . . . . . . . . 27
00110 M01S00110.coding +++| 3.2.8 PRIMARY SUBROUTINES . . . . . . . . . . . . . . . . 27
00111 M01S00111.coding +++| 3.2.9 SECONDARY SUBROUTINES . . . . . . . . . . . . . . . 27
00112 M01S00112.coding +++| 3.2.10 WORKING STORAGE AND BUFFERS . . . . . . . . . . . 27
00113 M01S00113.coding +++| 3.2.11 INITIALIZATION CODE . . . . . . . . . . . . . . . 27
00114 M01S00114.coding +++| 3.2.12 PROGRAM TERMINATION . . . . . . . . . . . . . . . 28
00115 M01S00115.coding +++| 3.3 INSTRUCTION USE, FORMAT AND PARAMETERS . . . . . . . . 28
00116 M01S00116.coding +++| 3.3.1 REGISTER USE AND SPECIFICATION . . . . . . . . . . 28
00117 M01S00117.coding +++| 3.3.1.1 B0 REGISTER USE . . . . . . . . . . . . . . . . . 28
00118 M01S00118.coding +++| 3.3.1.2 B1 REGISTER USE . . . . . . . . . . . . . . . . . 28
00119 M01S00119.coding +++| 3.3.1.3 PACK AND NOMINAL SHIFT X REGISTERS . . . . . . . 29
00120 M01S00120.coding +++| 3.3.1.4 UNPACK AND NORMALIZE X REGISTERS . . . . . . . . 29
00121 M01S00121.coding +++| 3.3.2 MULTIPLE LOGICAL TESTS . . . . . . . . . . . . . . 29
00122 M01S00122.coding +++| 3.3.3 SHIFT INSTRUCTION PARAMETERS . . . . . . . . . . . 29
00123 M01S00123.coding +++| 3.3.4 BOOLEAN MASK USAGE . . . . . . . . . . . . . . . . 31
00124 M01S00124.coding +++| 3.3.5 RELATIVE ADDRESSING . . . . . . . . . . . . . . . . 31
00125 M01S00125.coding +++| 3.3.6 JUMP INSTRUCTION USE . . . . . . . . . . . . . . . 31
00126 M01S00126.coding +++| 3.3.7 SUBROUTINE ENTRY . . . . . . . . . . . . . . . . . 32
00127 M01S00127.coding +++| 3.3.8 CPU CODE OPTIMIZATION . . . . . . . . . . . . . . . 33
00128 M01S00128.coding +++| 3.3.9 CLEARING PP MEMORY . . . . . . . . . . . . . . . . 34
00129 M01S00129.coding +++| 3.3.10 INSTRUCTION MODIFICATION . . . . . . . . . . . . . 34
00130 M01S00130.coding +++| 3.3.11 COMMON DECK REGISTER USAGE . . . . . . . . . . . . 37
00131 M01S00131.coding +++| 3.3.12 PP ADK, LDK, LMK, LPK, SBK MACRO USAGE . . . . . . 37
00132 M01S00132.coding +++| 3.4 DATA USE, FORMAT AND PARAMETERS . . . . . . . . . . . . 37
00133 M01S00133.coding +++| 3.4.1 LITERALS . . . . . . . . . . . . . . . . . . . . . 37
00134 M01S00134.coding +++| 3.4.2 DATA FORMATS . . . . . . . . . . . . . . . . . . . 37
00135 M01S00135.coding +++| 3.4.3 TABLE GENERATION . . . . . . . . . . . . . . . . . 38
00136 M01S00136.coding +++| 3.4.4 DIRECT CELL USE . . . . . . . . . . . . . . . . . . 38
00137 M01S00137.coding +++| 3.4.5 BUFFER DEFINITIONS . . . . . . . . . . . . . . . . 39
00138 M01S00138.coding +++|1 PAGE 4
00139 M01S00139.coding +++|
00140 M01S00140.coding +++|
00141 M01S00141.coding +++| 3.5 DATA/CODE NAMING TERMINOLOGY . . . . . . . . . . . . . 39
00142 M01S00142.coding +++| 3.5.1 USE OF CONDITION TERMINOLOGY . . . . . . . . . . . 40
00143 M01S00143.coding +++| 3.5.2 TAGS WITHIN SUBROUTINES . . . . . . . . . . . . . . 40
00144 M01S00144.coding +++| 3.5.3 TAGS ON DATA . . . . . . . . . . . . . . . . . . . 41
00145 M01S00145.coding +++| 3.5.3.1 DIRECT CELLS . . . . . . . . . . . . . . . . . . 41
00146 M01S00146.coding +++| 3.5.3.2 CODE CONTROL NAMES . . . . . . . . . . . . . . . 41
00147 M01S00147.coding +++| 3.5.3.3 TABLE NAMES . . . . . . . . . . . . . . . . . . . 41
00148 M01S00148.coding +++| 3.5.3.4 GLOBAL MEMORY LOCATIONS . . . . . . . . . . . . . 42
00149 M01S00149.coding +++| 3.5.4 CONSTANTS USED AS INSTRUCTIONS . . . . . . . . . . 42
00150 M01S00150.coding +++| 3.5.5 IF/ELSE/ENDIF SYMBOLS . . . . . . . . . . . . . . . 42
00151 M01S00151.coding +++| 3.5.6 NON-LOCAL MACRO SYMBOLS . . . . . . . . . . . . . . 42
00152 M01S00152.coding +++| 3.5.7 LOW CORE LOCATION SYMBOLS . . . . . . . . . . . . . 43
00153 M01S00153.coding +++| 3.5.8 CONTROL POINT AREA LOCATION SYMBOLS . . . . . . . . 43
00154 M01S00154.coding +++| 3.5.9 MONITOR FUNCTION SYMBOLS . . . . . . . . . . . . . 43
00155 M01S00155.coding +++| 3.5.10 NEGATIVE FIELD LENGTH SYMBOLS . . . . . . . . . . 43
00156 M01S00156.coding +++| 3.6 PSEUDO INSTRUCTION USE, FORMAT AND PARAMETERS . . . . . 43
00157 M01S00157.coding +++| 3.6.1 BASE AND POST RADIX USE . . . . . . . . . . . . . . 43
00158 M01S00158.coding +++| 3.6.2 EXTERNAL REFERENCES . . . . . . . . . . . . . . . . 43
00159 M01S00159.coding +++| 3.6.3 SPACE CARD FORMAT . . . . . . . . . . . . . . . . . 44
00160 M01S00160.coding +++| 3.6.4 CONDITIONAL CODE . . . . . . . . . . . . . . . . . 44
00161 M01S00161.coding +++| 3.6.5 MACROS . . . . . . . . . . . . . . . . . . . . . . 45
00162 M01S00162.coding +++| 3.6.6 DIS PSEUDO INSTRUCTION . . . . . . . . . . . . . . 45
00163 M01S00163.coding +++| 3.7 TESTS FOR OVERFLOW . . . . . . . . . . . . . . . . . . 46
00164 M01S00164.coding +++| 3.7.1 CM LOADS . . . . . . . . . . . . . . . . . . . . . 46
00165 M01S00165.coding +++| 3.7.2 TABLE OVERFLOW . . . . . . . . . . . . . . . . . . 46
00166 M01S00166.coding +++| 3.7.3 MASS STORAGE LOADS . . . . . . . . . . . . . . . . 47
00167 M01S00167.coding +++| 3.7.4 OVERLAY LOADS . . . . . . . . . . . . . . . . . . . 47
00168 M01S00168.coding +++| 3.8 RELOCATABLE CPU CODE . . . . . . . . . . . . . . . . . 47
00169 M01S00169.coding +++| 3.9 ROUTINE/SUBROUTINE . . . . . . . . . . . . . . . . . . 48
00170 M01S00170.coding +++|
00171 M01S00171.coding +++| 4.0 MISCELLANEOUS . . . . . . . . . . . . . . . . . . . . . 48
00172 M01S00172.coding +++| 4.1 PROGRAM NAMING . . . . . . . . . . . . . . . . . . . . 48
00173 M01S00173.coding +++| 4.1.1 LENGTH OF PROGRAM NAME . . . . . . . . . . . . . . 48
00174 M01S00174.coding +++| 4.1.2 RESERVED NAMES . . . . . . . . . . . . . . . . . . 49
00175 M01S00175.coding +++| 4.1.3 COMMON DECK NAMES . . . . . . . . . . . . . . . . . 49
00176 M01S00176.coding +++| 4.2 CODE TRANSMITTAL RULES . . . . . . . . . . . . . . . . 50
00177 M01S00177.coding +++| 4.2.1 GENERAL RULES . . . . . . . . . . . . . . . . . . . 50
00178 M01S00178.coding +++| 4.2.2 MODSET FORMAT . . . . . . . . . . . . . . . . . . . 50
00179 M01S00179.coding +++| 4.2.2.1 MODSET IDENTIFIER . . . . . . . . . . . . . . . . 51
00180 M01S00180.coding +++| 4.2.2.2 MODSET CORRECTION LETTER . . . . . . . . . . . . 52
00181 M01S00181.coding +++| 4.2.2.3 OVERFLOW . . . . . . . . . . . . . . . . . . . . 52
00182 M01S00182.coding +++| 4.2.2.4 MODSET EXAMPLE . . . . . . . . . . . . . . . . . 52
00183 M01S00183.coding +++| 4.3 INTERFACE CONSIDERATIONS . . . . . . . . . . . . . . . 53
00184 M01S00184.coding +++| 4.3.1 SYSTEM SUPPLIED INTERFACES . . . . . . . . . . . . 54
00185 M01S00185.coding +++| 4.3.2 PARAMETER VALIDATION . . . . . . . . . . . . . . . 54
00186 M01S00186.coding +++| 4.3.3 MEMORY ACCESS . . . . . . . . . . . . . . . . . . . 54
00187 M01S00187.coding +++| 4.3.4 SECURITY . . . . . . . . . . . . . . . . . . . . . 54
00188 M01S00188.coding +++| 4.3.5 RESERVATIONS AND INTERLOCKS . . . . . . . . . . . . 54
00189 M01S00189.coding +++| 4.3.6 DOCUMENTING HARDWARE DEFICIENCIES . . . . . . . . . 55
00190 M01S00190.coding +++| 4.3.7 NEW FUNCTION/LOW CORE IDENTIFIERS . . . . . . . . . 55
00191 M01S00191.coding +++| 4.3.8 DECK INTERDEPENDENCIES . . . . . . . . . . . . . . 55
00192 M01S00192.coding +++|1 PAGE 5
00193 M01S00193.coding +++|
00194 M01S00194.coding +++|
00195 M01S00195.coding +++| 4.4 MODULARITY . . . . . . . . . . . . . . . . . . . . . . 55
00196 M01S00196.coding +++| 4.4.1 PP OVERLAYS . . . . . . . . . . . . . . . . . . . . 55
00197 M01S00197.coding +++| 4.4.2 HELPER PP-S . . . . . . . . . . . . . . . . . . . . 56
00198 M01S00198.coding +++| 4.4.3 COMMON DECKS . . . . . . . . . . . . . . . . . . . 56
00199 M01S00199.coding +++| 4.5 DAYFILE MESSAGES . . . . . . . . . . . . . . . . . . . 56
00200 M01S00200.coding +++| 4.6 UNHANGABLE CHANNEL CODE . . . . . . . . . . . . . . . . 57
00201 M01S00201.coding +++| 4.7 SPECIAL ENTRY POINTS . . . . . . . . . . . . . . . . . 57
00202 M01S00202.coding +++| 4.8 SCRATCH FILE NAMES . . . . . . . . . . . . . . . . . . 58
00203 M01S00203.coding +++|
00204 M01S00204.coding +++| APPENDIX A - ABBREVIATIONS . . . . . . . . . . . . . . . . 59
00205 M01S00205.coding +++| A.1 GENERAL ABBREVIATIONS . . . . . . . . . . . . . . . . 59
00206 M01S00206.coding +++| A.2 NETWORK HOST PRODUCTS ABBREVIATIONS . . . . . . . . . 60
00207 M01S00207.coding +++| A.3 ACRONYMS . . . . . . . . . . . . . . . . . . . . . . 61
00208 M01S00208.coding +++|
00209 M01S00209.coding +++| APPENDIX B - ERROR MESSAGE GUIDELINES . . . . . . . . . . . 62
00210 M01S00210.coding +++|
00211 M01S00211.coding +++| APPENDIX C - DOCUMENTATION/USABILITY GUIDELINES . . . . . . 64
00212 M01S00212.coding +++|
00213 M01S00213.coding +++|
00214 M01S00214.coding +++|1 PAGE 6
00215 M01S00215.coding +++|
00216 M01S00216.coding +++|
00217 M01S00217.coding +++| 1.0 INTRODUCTION
00218 M01S00218.coding +++|
00219 M01S00219.coding +++|
00220 M01S00220.coding +++| 1.1 SCOPE OF DOCUMENT
00221 M01S00221.coding +++|
00222 M01S00222.coding +++|
00223 M01S00223.coding +++| 1.1.1 PURPOSE
00224 M01S00224.coding +++|
00225 M01S00225.coding +++| This document establishes standard procedures to be used by
00226 M01S00226.coding +++| programmers in the development and maintenance of programs in
00227 M01S00227.coding +++| COMPASS Assembly Language.
00228 M01S00228.coding +++|
00229 M01S00229.coding +++| This document should be used by programmers as a reference manual of
00230 M01S00230.coding +++| standard programming procedures. The implementation of these
00231 M01S00231.coding +++| procedures will increase the efficiency of program development,
00232 M01S00232.coding +++| improve the reliability and maintainability of the program and aid
00233 M01S00233.coding +++| in the training of persons who will be maintaining or using the
00234 M01S00234.coding +++| program.
00235 M01S00235.coding +++|
00236 M01S00236.coding +++|
00237 M01S00237.coding +++| 1.1.2 SCOPE OF USE
00238 M01S00238.coding +++|
00239 M01S00239.coding +++| The procedures defined in this document are applicable to the
00240 M01S00240.coding +++| NETWORK OPERATING SYSTEM (NOS) and its related subsystems.
00241 M01S00241.coding +++|
00242 M01S00242.coding +++|
00243 M01S00243.coding +++| 1.2 CONFORMANCE AND ENFORCEMENT
00244 M01S00244.coding +++|
00245 M01S00245.coding +++| The procedures defined in this document are to be used in all newly
00246 M01S00246.coding +++| developed programs. In existing programs these procedures should be
00247 M01S00247.coding +++| used if they are not inconsistent with the existing procedures. If
00248 M01S00248.coding +++| major changes (such as a rewritten subroutine or a new overlay) are
00249 M01S00249.coding +++| made to a program, these procedures are to be used for the changes.
00250 M01S00250.coding +++|
00251 M01S00251.coding +++| Programs which do not conform to these requirements will be returned
00252 M01S00252.coding +++| to the programmer for correction.
00253 M01S00253.coding +++|
00254 M01S00254.coding +++|
00255 M01S00255.coding +++|
00256 M01S00256.coding +++|1 PAGE 7
00257 M01S00257.coding +++|
00258 M01S00258.coding +++|
00259 M01S00259.coding +++| 2.0 DOCUMENTATION
00260 M01S00260.coding +++|
00261 M01S00261.coding +++|
00262 M01S00262.coding +++| 2.1 INTRODUCTION
00263 M01S00263.coding +++|
00264 M01S00264.coding +++| Documentation is the presentation of information about a program in
00265 M01S00265.coding +++| easily understandable form so that those who need to understand the
00266 M01S00266.coding +++| program do not need to study the program itself. This reduces the
00267 M01S00267.coding +++| time consumed from days or weeks to just minutes or hours.
00268 M01S00268.coding +++|
00269 M01S00269.coding +++| The program documentation presented in this standard is embedded
00270 M01S00270.coding +++| within the source language of each program. The documentation is
00271 M01S00271.coding +++| designed to be extractable by the standard documentation processing
00272 M01S00272.coding +++| program, DOCMENT. This approach serves to unify the program and its
00273 M01S00273.coding +++| documentation, making it easier and more natural to update the
00274 M01S00274.coding +++| documentation as changes are made to the code.
00275 M01S00275.coding +++|
00276 M01S00276.coding +++| The effectiveness of documentation is judged by its success in
00277 M01S00277.coding +++| meeting the needs of those who use it. This introduction defines
00278 M01S00278.coding +++| four distinct needs for documentation which arise during the life of
00279 M01S00279.coding +++| a software product. Sections 2.3 through 2.5 define three levels of
00280 M01S00280.coding +++| documentation (Program Level, Subroutine Level and Code Level) which
00281 M01S00281.coding +++| together meet these needs.
00282 M01S00282.coding +++|
00283 M01S00283.coding +++| Section 2.7 gives examples of proper documentation.
00284 M01S00284.coding +++|
00285 M01S00285.coding +++|
00286 M01S00286.coding +++| 2.1.1 DESIGN OVERVIEW
00287 M01S00287.coding +++|
00288 M01S00288.coding +++| Anyone wanting to know the structure of the system, or some
00289 M01S00289.coding +++| functional area, does not want excessively detailed information
00290 M01S00290.coding +++| which will make the task more difficult. One should be able to ask
00291 M01S00291.coding +++| the question:
00292 M01S00292.coding +++|
00293 M01S00293.coding +++| What is the function of this program?
00294 M01S00294.coding +++|
00295 M01S00295.coding +++| and get an answer that is brief and to the point. It should not
00296 M01S00296.coding +++| contain any information about the input parameters, options, error
00297 M01S00297.coding +++| conditions, or internal workings of the program.
00298 M01S00298.coding +++|
00299 M01S00299.coding +++|
00300 M01S00300.coding +++| 2.1.2 EXTERNAL INTERFACE
00301 M01S00301.coding +++|
00302 M01S00302.coding +++| Anyone who knows the function of a program and wants to know how to
00303 M01S00303.coding +++| interface to the program needs to know the form of the call, what
00304 M01S00304.coding +++| parameters to supply, what information is returned, and what is
00305 M01S00305.coding +++| accomplished. One should be able to ask the question:
00306 M01S00306.coding +++|1 PAGE 8
00307 M01S00307.coding +++|
00308 M01S00308.coding +++|
00309 M01S00309.coding +++|
00310 M01S00310.coding +++| How is this program used?
00311 M01S00311.coding +++|
00312 M01S00312.coding +++| and get an answer that lists the parameter definitions, formats, and
00313 M01S00313.coding +++| contents, the initial conditions of buffers and devices, any status
00314 M01S00314.coding +++| and condition information, a list of other programs called, and a
00315 M01S00315.coding +++| complete list of error codes, error messages issued and parameters
00316 M01S00316.coding +++| returned. A general description of the actions taken should be
00317 M01S00317.coding +++| included for each function performed that is recognizable by the
00318 M01S00318.coding +++| calling program.
00319 M01S00319.coding +++|
00320 M01S00320.coding +++|
00321 M01S00321.coding +++| 2.1.3 INTERNAL OPERATION
00322 M01S00322.coding +++|
00323 M01S00323.coding +++| Anyone working on a modification or enhancement to the system needs
00324 M01S00324.coding +++| a general knowledge of the internal operation of a program. This
00325 M01S00325.coding +++| requires finding out where within the program some function is
00326 M01S00326.coding +++| performed and how it is performed. One should be able to ask the
00327 M01S00327.coding +++| question:
00328 M01S00328.coding +++|
00329 M01S00329.coding +++| How does this program work?
00330 M01S00330.coding +++|
00331 M01S00331.coding +++| and get an answer that includes a description of the logical flow
00332 M01S00332.coding +++| and structure of the program, the algorithms used and the function
00333 M01S00333.coding +++| performed by each overlay or subroutine in the program.
00334 M01S00334.coding +++|
00335 M01S00335.coding +++|
00336 M01S00336.coding +++| 2.1.4 DETAILED CODE ANALYSIS
00337 M01S00337.coding +++|
00338 M01S00338.coding +++| Anyone attempting to modify the program or establish a knowledge of
00339 M01S00339.coding +++| the detailed operation of a program uses the listing. Documentation
00340 M01S00340.coding +++| should be provided in the listing to aid in following the flow of
00341 M01S00341.coding +++| the program without reading all of the code. This documentation
00342 M01S00342.coding +++| consists of comments within the code itself. Comments describing
00343 M01S00343.coding +++| the function of logical groups of instructions should be provided,
00344 M01S00344.coding +++| and comments documenting table structures, data areas, and constants
00345 M01S00345.coding +++| should appear on the instructions which define them. One should be
00346 M01S00346.coding +++| able to ask the question:
00347 M01S00347.coding +++|
00348 M01S00348.coding +++| What should I know when modifying this program?
00349 M01S00349.coding +++|
00350 M01S00350.coding +++| and get back an answer with all the detail needed to make the
00351 M01S00351.coding +++| modifications without adversely affecting existing program functions.
00352 M01S00352.coding +++|
00353 M01S00353.coding +++|
00354 M01S00354.coding +++|1 PAGE 9
00355 M01S00355.coding +++|
00356 M01S00356.coding +++|
00357 M01S00357.coding +++| 2.2 GENERAL REQUIREMENTS
00358 M01S00358.coding +++|
00359 M01S00359.coding +++|
00360 M01S00360.coding +++| 2.2.1 ABBREVIATIONS
00361 M01S00361.coding +++|
00362 M01S00362.coding +++| The abbreviations for technical terms which are to be used in
00363 M01S00363.coding +++| program documentation are listed in Appendix A. All other technical
00364 M01S00364.coding +++| words and phrases are completely spelled out. Routine names and
00365 M01S00365.coding +++| mnemonic names of tables and equipments are not considered
00366 M01S00366.coding +++| abbreviations.
00367 M01S00367.coding +++|
00368 M01S00368.coding +++| A program whose documentation makes extensive use of terms not in
00369 M01S00369.coding +++| this list may define a list of abbreviations and include it in the
00370 M01S00370.coding +++| first section of the internal documentation for the program. Such
00371 M01S00371.coding +++| abbreviations may not be used in the program overview or external
00372 M01S00372.coding +++| documentation.
00373 M01S00373.coding +++|
00374 M01S00374.coding +++| The following standard symbols are used in the documentation when
00375 M01S00375.coding +++| expressing logical and arithmetic comparisons:
00376 M01S00376.coding +++|
00377 M01S00377.coding +++| .NOT. logical inverse
00378 M01S00378.coding +++| .XOR. logical difference (exclusive or)
00379 M01S00379.coding +++| .AND. logical product
00380 M01S00380.coding +++| .OR. Logical sum (inclusive or)
00381 M01S00381.coding +++| .EQ. equal to
00382 M01S00382.coding +++| .NE. Not equal to
00383 M01S00383.coding +++| .LE. Less than or equal to
00384 M01S00384.coding +++| .GE. Greater than or equal to
00385 M01S00385.coding +++| .LT. Less than
00386 M01S00386.coding +++| .GT. Greater than
00387 M01S00387.coding +++| = equal to
00388 M01S00388.coding +++| () contents of
00389 M01S00389.coding +++| (()) contents of the contents of (indirect addressing)
00390 M01S00390.coding +++|
00391 M01S00391.coding +++|
00392 M01S00392.coding +++| 2.2.2 PUNCTUATION
00393 M01S00393.coding +++|
00394 M01S00394.coding +++| All documentation and comment lines contain complete English
00395 M01S00395.coding +++| sentences with correct punctuation. Exceptions are allowed in
00396 M01S00396.coding +++| subroutine headings (see section 2.4) and in embedded comments (see
00397 M01S00397.coding +++| section 2.5.2). Titles (such as "Assembly Constants.") should end
00398 M01S00398.coding +++| with a period but need not be complete sentences. Each comment
00399 M01S00399.coding +++| (excluding embedded comments) should end with a period even if it is
00400 M01S00400.coding +++| not a sentence.
00401 M01S00401.coding +++|
00402 M01S00402.coding +++| Correct punctuation means the same punctuation as required in
00403 M01S00403.coding +++| written English. However, the apostrophe presents problems due to
00404 M01S00404.coding +++| character set and print train differences, and plurals of
00405 M01S00405.coding +++| abbreviations are not readable without upper and lower case.
00406 M01S00406.coding +++| Therefore, plurals and possessive forms of abbreviated terms are to
00407 M01S00407.coding +++| be avoided. Authorized abbreviations (see section 2.2.1) are made
00408 M01S00408.coding +++| plural by adding a hyphen and the letter "s" (e.g. PP-S).
00409 M01S00409.coding +++|
00410 M01S00410.coding +++|1 PAGE 10
00411 M01S00411.coding +++|
00412 M01S00412.coding +++|
00413 M01S00413.coding +++| If an upper case item is to be indicated in the documentation, it is
00414 M01S00414.coding +++| enclosed within asterisks. Upper case is used for names of files,
00415 M01S00415.coding +++| programs, calling parameters, subroutine tags, table names and any
00416 M01S00416.coding +++| other words that are normally capitalized . Accepted abbreviations,
00417 M01S00417.coding +++| acronyms, and programming language names are not enclosed in
00418 M01S00418.coding +++| asterisks even if they would normally be capitalized (refer to
00419 M01S00419.coding +++| Appendix A and section 2.2.1). Tables defined in CMR do not need
00420 M01S00420.coding +++| asterisks (EJT, QFT, etc.).
00421 M01S00421.coding +++|
00422 M01S00422.coding +++| 2.2.3 FORMATS
00423 M01S00423.coding +++|
00424 M01S00424.coding +++| Documentation lines contain only asterisks and blanks in the first
00425 M01S00425.coding +++| ten columns and text in columns 11 through 71. The text is written
00426 M01S00426.coding +++| using correct English except where specifically noted. The format
00427 M01S00427.coding +++| for each of the various types of documentation is shown below.
00428 M01S00428.coding +++| Later sections define the usage of each type of
00429 M01S00429.coding +++| documentation.
00430 M01S00430.coding +++|
00431 M01S00431.coding +++| External - Asterisks in columns 1 through 3 (***).
00432 M01S00432.coding +++| This line indicates that this and the
00433 M01S00433.coding +++| following contiguous comment lines are to be
00434 M01S00434.coding +++| included in the program external
00435 M01S00435.coding +++| documentation.
00436 M01S00436.coding +++|
00437 M01S00437.coding +++| Internal - Asterisks in columns 1 and 2 (**). This
00438 M01S00438.coding +++| line indicates that this and the following
00439 M01S00439.coding +++| contiguous comment lines are to be included
00440 M01S00440.coding +++| in the program internal documentation.
00441 M01S00441.coding +++|
00442 M01S00442.coding +++| Internal Bracket - Asterisks in columns 1 through 4 (****).
00443 M01S00443.coding +++| This line and all other lines up to and
00444 M01S00444.coding +++| including the next occurrence of this line
00445 M01S00445.coding +++| are to be included in the program internal
00446 M01S00446.coding +++| documentation.
00447 M01S00447.coding +++|
00448 M01S00448.coding +++| Other Comment - Asterisk in column 1 (*). This type of
00449 M01S00449.coding +++| comment is used for continuation of the
00450 M01S00450.coding +++| above types of documentation. It is also
00451 M01S00451.coding +++| used for stand-alone comments (see section
00452 M01S00452.coding +++| 2.5.1).
00453 M01S00453.coding +++|
00454 M01S00454.coding +++| Table - Asterisk in column 1, T in column 2 (*T).
00455 M01S00455.coding +++| This line indicates the beginning of table
00456 M01S00456.coding +++| documentation. The *T lines must appear
00457 M01S00457.coding +++| within consecutive comment lines beginning
00458 M01S00458.coding +++| with an external (***) or internal (**)
00459 M01S00459.coding +++| statement. DOCMENT generates a table
00460 M01S00460.coding +++| diagram from the field widths and
00461 M01S00461.coding +++| descriptions in the *T documentation. Note
00462 M01S00462.coding +++| that the field description size (including
00463 M01S00463.coding +++| blanks) cannot exceed the field width size
00464 M01S00464.coding +++| (to prevent truncation). A DOCMENT listing
00465 M01S00465.coding +++| should be made of a program's
00466 M01S00466.coding +++| external/internal documentation when table
00467 M01S00467.coding +++| structures are added (to verify correctness).
00468 M01S00468.coding +++|1 PAGE 11
00469 M01S00469.coding +++|
00470 M01S00470.coding +++|
00471 M01S00471.coding +++| Table Continuation - Asterisk in column 1, T in column 2, comma
00472 M01S00472.coding +++| in column 3 (*T,). This type of comment is
00473 M01S00473.coding +++| used for continuation of table documentation
00474 M01S00474.coding +++| started by a *T line.
00475 M01S00475.coding +++|
00476 M01S00476.coding +++| Blank Comment Line - A line with an asterisk in column 1 (*) and
00477 M01S00477.coding +++| blanks in columns 2 through 71 is called a
00478 M01S00478.coding +++| "Blank Comment Line or "Blank Comment Card"
00479 M01S00479.coding +++| and is used as a separator to improve
00480 M01S00480.coding +++| readability of documentation.
00481 M01S00481.coding +++|
00482 M01S00482.coding +++|
00483 M01S00483.coding +++| 2.2.4 FORMAT OF ITEMIZED DOCUMENTATION
00484 M01S00484.coding +++|
00485 M01S00485.coding +++| Documentation which contains several separate items of information
00486 M01S00486.coding +++| (as found in sections 2.3.1, 2.3.2, 2.3.3 and 2.4) contains a Blank
00487 M01S00487.coding +++| Comment Line between the items. Each item ends with a period. If
00488 M01S00488.coding +++| an item is not applicable,it is omitted from the documentation. The
00489 M01S00489.coding +++| items are placed in the order specified and the last item is
00490 M01S00490.coding +++| followed by a SPACE 4,10 line.
00491 M01S00491.coding +++|
00492 M01S00492.coding +++|
00493 M01S00493.coding +++| 2.3 PROGRAM LEVEL DOCUMENTATION
00494 M01S00494.coding +++|
00495 M01S00495.coding +++| Every program contains comment lines which make up the Program Level
00496 M01S00496.coding +++| documentation (as defined in this section). This level of
00497 M01S00497.coding +++| documentation may be used with the program listing or without it
00498 M01S00498.coding +++| (using extracted documentation produced by a documentation
00499 M01S00499.coding +++| processor). Even without the listing, the Program Level
00500 M01S00500.coding +++| documentation satisfies the Design Overview, External Interface and
00501 M01S00501.coding +++| Internal Operation documentation needs discussed in section 2.1.
00502 M01S00502.coding +++|
00503 M01S00503.coding +++|
00504 M01S00504.coding +++| 2.3.1 OVERVIEW
00505 M01S00505.coding +++|
00506 M01S00506.coding +++| The overview documentation is placed immediately following the
00507 M01S00507.coding +++| COMPASS Group 1 instructions and before any other documentation,
00508 M01S00508.coding +++| macro definitions or executable code (see section 3.2). It consists
00509 M01S00509.coding +++| of an external documentation line (see section 2.2.3) which contains
00510 M01S00510.coding +++| the program name and a brief description of the program, and
00511 M01S00511.coding +++| additional comment lines which contain the following items of data
00512 M01S00512.coding +++| (see section 2.7 for the layout of these items):
00513 M01S00513.coding +++|
00514 M01S00514.coding +++| . Name of author and date written (yy/mm/dd).
00515 M01S00515.coding +++| . Names of authors of major modifications, with dates.
00516 M01S00516.coding +++| . Text of overview of program.
00517 M01S00517.coding +++|
00518 M01S00518.coding +++| The text of the overview should follow the general definition of
00519 M01S00519.coding +++| Design Overview documentation in section 2.1. The objective is to
00520 M01S00520.coding +++| describe the function of the program in general terms.
00521 M01S00521.coding +++|
00522 M01S00522.coding +++|
00523 M01S00523.coding +++|1 PAGE 12
00524 M01S00524.coding +++|
00525 M01S00525.coding +++|
00526 M01S00526.coding +++| 2.3.2 EXTERNAL
00527 M01S00527.coding +++|
00528 M01S00528.coding +++| The external documentation is placed immediately following the
00529 M01S00529.coding +++| overview documentation and before any internal documentation, macro
00530 M01S00530.coding +++| definitions or executable code (see section 3.2). It consists of an
00531 M01S00531.coding +++| external documentation line (see section 2.2.3) and additional
00532 M01S00532.coding +++| comment lines which together contain the following items of data
00533 M01S00533.coding +++| (see section 2.7 for the layout of these items):
00534 M01S00534.coding +++|
00535 M01S00535.coding +++| . Detailed description of functions and options.
00536 M01S00536.coding +++| . Entry conditions, including parameters and initial
00537 M01S00537.coding +++| conditions of buffers and external tables.
00538 M01S00538.coding +++| . Command format.
00539 M01S00539.coding +++| . Exit conditions, including status bits and fields returned.
00540 M01S00540.coding +++| . Errors detected, error codes returned, including subsequent
00541 M01S00541.coding +++| action taken for each.
00542 M01S00542.coding +++| . System errors detected and subsequent action taken.
00543 M01S00543.coding +++| . Other programs called.
00544 M01S00544.coding +++| . Messages issued (including dayfile and operator).
00545 M01S00545.coding +++|
00546 M01S00546.coding +++| The content of this section follows the general definition of
00547 M01S00547.coding +++| External Interface documentation in section 2.1. The objective is
00548 M01S00548.coding +++| to supply information required by a potential user of the program.
00549 M01S00549.coding +++|
00550 M01S00550.coding +++|
00551 M01S00551.coding +++| 2.3.3 INTERNAL
00552 M01S00552.coding +++|
00553 M01S00553.coding +++| The internal documentation describes the internal workings of the
00554 M01S00554.coding +++| program. It may be dispersed throughout a program as desired,
00555 M01S00555.coding +++| however a major portion appears immediately following the external
00556 M01S00556.coding +++| documentation. Internal documentation consists of an internal
00557 M01S00557.coding +++| documentation line (see section 2.2.3) and additional comment lines
00558 M01S00558.coding +++| which together contain the following items of data (see section
00559 M01S00559.coding +++| 2.2.4 for the layout of these items):
00560 M01S00560.coding +++|
00561 M01S00561.coding +++| . System texts required for assembly (other than default).
00562 M01S00562.coding +++| . Direct cell usage (PP programs).
00563 M01S00563.coding +++| . Global register assignments (CPU programs).
00564 M01S00564.coding +++| . Data areas and table formats.
00565 M01S00565.coding +++| . Memory map (if overlays are used).
00566 M01S00566.coding +++|
00567 M01S00567.coding +++| Other items to be included if applicable are:
00568 M01S00568.coding +++|
00569 M01S00569.coding +++| . Techniques or algorithms employed where not obvious.
00570 M01S00570.coding +++| . Timing considerations.
00571 M01S00571.coding +++| . Interlock considerations.
00572 M01S00572.coding +++| . Known limitations to performance or extensibility, such as
00573 M01S00573.coding +++| timing of loops, core size, error-recovery deficiencies.
00574 M01S00574.coding +++|
00575 M01S00575.coding +++|1 PAGE 13
00576 M01S00576.coding +++|
00577 M01S00577.coding +++|
00578 M01S00578.coding +++| Any other information which would aid someone in understanding the
00579 M01S00579.coding +++| internal workings of the program is also provided, including logical
00580 M01S00580.coding +++| flow, structure, and pitfalls to redesign.
00581 M01S00581.coding +++|
00582 M01S00582.coding +++|
00583 M01S00583.coding +++| 2.4 SUBROUTINE LEVEL DOCUMENTATION
00584 M01S00584.coding +++|
00585 M01S00585.coding +++| The heading of any subroutine consists of comment lines giving a
00586 M01S00586.coding +++| brief description of its function, its entry and exit conditions,
00587 M01S00587.coding +++| register or direct cell usage and internal workings. The
00588 M01S00588.coding +++| information contained should be on a level indicated by the
00589 M01S00589.coding +++| complexity of the subroutine. The following items of data should be
00590 M01S00590.coding +++| included (see sections 2.7.2 and 2.7.3 for the layout of these
00591 M01S00591.coding +++| items):
00592 M01S00592.coding +++|
00593 M01S00593.coding +++| . TITLE line with name as subtitle (primary subroutine)
00594 M01S00594.coding +++| . SPACE line (see section 3.6.3)
00595 M01S00595.coding +++| . Internal comment line giving name and title of subroutine
00596 M01S00596.coding +++| . One or more sentences describing the function of the
00597 M01S00597.coding +++| subroutine (optional but desirable).
00598 M01S00598.coding +++| . Entry conditions (list)
00599 M01S00599.coding +++| . Exit conditions (list)
00600 M01S00600.coding +++| . Error exit conditions (list)
00601 M01S00601.coding +++| . Register or direct cell usage (list)
00602 M01S00602.coding +++| . Routines called (list)
00603 M01S00603.coding +++| . Macros called (list)
00604 M01S00604.coding +++| . Description of allocated registers
00605 M01S00605.coding +++| . Timing considerations, if critical
00606 M01S00606.coding +++| . Design, implementation and general information
00607 M01S00607.coding +++| . Two blank lines
00608 M01S00608.coding +++|
00609 M01S00609.coding +++| The title of the subroutine should describe the action performed by
00610 M01S00610.coding +++| the subroutine (for example, Position Mass Storage, Make Queue
00611 M01S00611.coding +++| Entry). This means that titles should always contain a verb.
00612 M01S00612.coding +++| Titles without verbs should be used for groups of subroutines and
00613 M01S00613.coding +++| COMSxxx decks.
00614 M01S00614.coding +++|
00615 M01S00615.coding +++| Defined formats exist for the list of items in the subroutine
00616 M01S00616.coding +++| heading. A keyword appears in column 11, followed by text in column
00617 M01S00617.coding +++| 18. The text is simply a list, rather than complete sentences. Any
00618 M01S00618.coding +++| list requiring more than one line is continued beginning in column
00619 M01S00619.coding +++| 18 (or beyond) of the next comment line. The formats are shown
00620 M01S00620.coding +++| below. Each list ends with a period. Acceptable keywords include:
00621 M01S00621.coding +++|
00622 M01S00622.coding +++| ENTRY Entry conditions.
00623 M01S00623.coding +++| EXIT Exit conditions.
00624 M01S00624.coding +++| ERROR Error exit conditions.
00625 M01S00625.coding +++| USES Register or direct cells destroyed.
00626 M01S00626.coding +++| CALLS Routines called.
00627 M01S00627.coding +++| XREF Common or system decks required.
00628 M01S00628.coding +++|1 PAGE 14
00629 M01S00629.coding +++|
00630 M01S00630.coding +++|
00631 M01S00631.coding +++| MACROS Macros called.
00632 M01S00632.coding +++| DEFINE list of allocatable registers.
00633 M01S00633.coding +++| TIMING Description of timing considerations.
00634 M01S00634.coding +++| NOTES Programming information.
00635 M01S00635.coding +++|
00636 M01S00636.coding +++| Documentation for common decks and zero level overlays should
00637 M01S00637.coding +++| include subroutine level documentation where appropriate.
00638 M01S00638.coding +++|
00639 M01S00639.coding +++|
00640 M01S00640.coding +++| 2.4.1 ENTRY CONDITIONS (ENTRY)
00641 M01S00641.coding +++|
00642 M01S00642.coding +++| Entry conditions include the following items:
00643 M01S00643.coding +++|
00644 M01S00644.coding +++| Registers, direct cells or memory locations that must be set before
00645 M01S00645.coding +++| the subroutine is called.
00646 M01S00646.coding +++|
00647 M01S00647.coding +++| Logical status of channels, files, etc.,(i.e. Channels reserved,
00648 M01S00648.coding +++| files set busy, disk postioned, files positioned) that should exist
00649 M01S00649.coding +++| before the subroutine is called.
00650 M01S00650.coding +++|
00651 M01S00651.coding +++| Only one entry condition may be specified per line. For PP code,
00652 M01S00652.coding +++| the contents of the A register should be described first.
00653 M01S00653.coding +++|
00654 M01S00654.coding +++|
00655 M01S00655.coding +++| 2.4.2 EXIT CONDITIONS (EXIT)
00656 M01S00656.coding +++|
00657 M01S00657.coding +++| Exit conditions include the following items:
00658 M01S00658.coding +++|
00659 M01S00659.coding +++| Registers, direct cells or memory locations that may be used by
00660 M01S00660.coding +++| subsequent routines.
00661 M01S00661.coding +++|
00662 M01S00662.coding +++| Logical status of channels, files, etc., (i.e. Channels reserved,
00663 M01S00663.coding +++| files set busy, disk positioned, files postioned) that exist when
00664 M01S00664.coding +++| the subroutine is exited.
00665 M01S00665.coding +++|
00666 M01S00666.coding +++| Only one exit condition is listed per line. For PP code, the
00667 M01S00667.coding +++| contents of the A register should be described first.
00668 M01S00668.coding +++|
00669 M01S00669.coding +++| Branches (not CALLs) to other routines.
00670 M01S00670.coding +++|
00671 M01S00671.coding +++|
00672 M01S00672.coding +++| 2.4.3 ERROR EXIT CONDITIONS (ERROR)
00673 M01S00673.coding +++|
00674 M01S00674.coding +++| Error exit conditions include all exit conditions that exist when a
00675 M01S00675.coding +++| special termination of the subroutine, such as a jump to an error
00676 M01S00676.coding +++| processor, is taken. Error conditions include the following items:
00677 M01S00677.coding +++|
00678 M01S00678.coding +++| . The label being jumped to and the conditions that caused
00679 M01S00679.coding +++| the special exit.
00680 M01S00680.coding +++|
00681 M01S00681.coding +++|1 PAGE 15
00682 M01S00682.coding +++|
00683 M01S00683.coding +++|
00684 M01S00684.coding +++| . Registers, direct cells or memory locations that may be
00685 M01S00685.coding +++| used by subsequent routines.
00686 M01S00686.coding +++|
00687 M01S00687.coding +++| . Logical status of channels, files, etc., (i.e. Channels
00688 M01S00688.coding +++| reserved, files set busy, disk positioned, files postioned)
00689 M01S00689.coding +++| that exist when the subroutine is exited.
00690 M01S00690.coding +++|
00691 M01S00691.coding +++| Only one exit condition is listed per line. The label being
00692 M01S00692.coding +++| jumped to is documented first with all exit conditions pertaining
00693 M01S00693.coding +++| to that exit following. If these are multiple error exits, each
00694 M01S00694.coding +++| with unique conditions, the conditions should be listed under their
00695 M01S00695.coding +++| own exits.
00696 M01S00696.coding +++|
00697 M01S00697.coding +++|
00698 M01S00698.coding +++| 2.4.4 REGISTER OR DIRECT CELL USAGE (USES)
00699 M01S00699.coding +++|
00700 M01S00700.coding +++| Registers or direct cells used include all registers or direct cells
00701 M01S00701.coding +++| destroyed by that subroutine only. Registers or direct cells
00702 M01S00702.coding +++| destroyed by subroutines or MACROS called by a routine are not
00703 M01S00703.coding +++| listed.
00704 M01S00704.coding +++|
00705 M01S00705.coding +++| For CPU code, the format of the USES block includes a register type
00706 M01S00706.coding +++| (X - operand register, A - address register, B - index register)
00707 M01S00707.coding +++| followed by a sequence of ascending numbers indicating the registers
00708 M01S00708.coding +++| used. The term ALL may be substituted if all registers are used by
00709 M01S00709.coding +++| a routine.
00710 M01S00710.coding +++|
00711 M01S00711.coding +++| Example:
00712 M01S00712.coding +++|
00713 M01S00713.coding +++| * USES X - 0, 1, 6.
00714 M01S00714.coding +++| * A - 1, 6.
00715 M01S00715.coding +++| * B - 3, 7.
00716 M01S00716.coding +++|
00717 M01S00717.coding +++| Indicates the following registers are used:
00718 M01S00718.coding +++|
00719 M01S00719.coding +++| X0, X1, X6, A1, A6, B3, B7.
00720 M01S00720.coding +++|
00721 M01S00721.coding +++|
00722 M01S00722.coding +++| For PP code, single direct cells are listed in alphabetical order
00723 M01S00723.coding +++| followed by multiple direct cells listed in alphabetical order.
00724 M01S00724.coding +++|
00725 M01S00725.coding +++| Example:
00726 M01S00726.coding +++|
00727 M01S00727.coding +++| * USES T1, T2, T5, CM - CM+4, RI - RI+4.
00728 M01S00728.coding +++|
00729 M01S00729.coding +++| The direct cell at PP memory location 0 (T0) is assumed to be used
00730 M01S00730.coding +++| by every subroutine unless otherwise stated in the ENTRY/EXIT
00731 M01S00731.coding +++| conditions. This is because certain instructions, such as CRM and
00732 M01S00732.coding +++| CWM, destroy location zero.
00733 M01S00733.coding +++|
00734 M01S00734.coding +++|
00735 M01S00735.coding +++|1 PAGE 16
00736 M01S00736.coding +++|
00737 M01S00737.coding +++|
00738 M01S00738.coding +++| 2.4.5 ROUTINES CALLED (CALLS)
00739 M01S00739.coding +++|
00740 M01S00740.coding +++| Routines called by a subroutine include all subroutines, common
00741 M01S00741.coding +++| decks and overlays that are explicitly called. Routines called by
00742 M01S00742.coding +++| macros are not to be included. Where the routine called does not
00743 M01S00743.coding +++| return to the calling point, the branch is an EXIT condition rather
00744 M01S00744.coding +++| than a CALL.
00745 M01S00745.coding +++|
00746 M01S00746.coding +++| 2.4.6 COMMON OR SYSTEM DECKS REQUIRED (XREF)
00747 M01S00747.coding +++|
00748 M01S00748.coding +++| When a routine, macro, or common deck requires a particular common
00749 M01S00749.coding +++| or system deck for assembly or for correct execution, it is valuable
00750 M01S00750.coding +++| to list the deck(s) required.
00751 M01S00751.coding +++|
00752 M01S00752.coding +++| Example:
00753 M01S00753.coding +++|
00754 M01S00754.coding +++| * XREF COMCLOD, COMCRTN.
00755 M01S00755.coding +++|
00756 M01S00756.coding +++| 2.4.7 MACROS CALLED (MACROS)
00757 M01S00757.coding +++|
00758 M01S00758.coding +++| Macros called include all macros that are explicitly called by a
00759 M01S00759.coding +++| subroutine. The SUBR macro is always implied to be called and need
00760 M01S00760.coding +++| not be listed. PP macros ADK, LDK, LMK, LPK, SBK, MJP, NJP, PJP,
00761 M01S00761.coding +++| UJP, and ZJP need not be listed.
00762 M01S00762.coding +++|
00763 M01S00763.coding +++|
00764 M01S00764.coding +++| 2.4.8 ALLOCATED REGISTERS OR DIRECT CELLS (DEFINE)
00765 M01S00765.coding +++|
00766 M01S00766.coding +++| Allocated registers are registers (or direct cells for PP code)
00767 M01S00767.coding +++| used for well defined items throughout a particular subroutine or
00768 M01S00768.coding +++| program.
00769 M01S00769.coding +++|
00770 M01S00770.coding +++|
00771 M01S00771.coding +++| 2.4.9 TIMING CONSIDERATIONS (TIMING)
00772 M01S00772.coding +++|
00773 M01S00773.coding +++| Timing considerations should describe any timing limitations that
00774 M01S00774.coding +++| are imposed on the subroutine because of hardware or performance
00775 M01S00775.coding +++| constraints. Care should be taken to express units of time in a
00776 M01S00776.coding +++| manner independent of machine type. For example, units of time
00777 M01S00777.coding +++| expressed in cycles rather than microseconds is more desirable.
00778 M01S00778.coding +++| This is because the same routine may execute faster or slower than
00779 M01S00779.coding +++| stated depending on the type of the PP or CPU it executes in.
00780 M01S00780.coding +++|
00781 M01S00781.coding +++|
00782 M01S00782.coding +++| 2.4.10 PROGRAMMING NOTES (NOTES)
00783 M01S00783.coding +++|
00784 M01S00784.coding +++| This section documents design, implementation and general
00785 M01S00785.coding +++| information that may be useful to other analysts. Information in
00786 M01S00786.coding +++| this section pertains to the subroutine only.
00787 M01S00787.coding +++|
00788 M01S00788.coding +++|
00789 M01S00789.coding +++|1 PAGE 17
00790 M01S00790.coding +++|
00791 M01S00791.coding +++|
00792 M01S00792.coding +++| 2.5 CODE LEVEL DOCUMENTATION
00793 M01S00793.coding +++|
00794 M01S00794.coding +++| All documentation which is not described in one of the preceding
00795 M01S00795.coding +++| sections of this document falls into the category of Code Level
00796 M01S00796.coding +++| documentation. The requirements for this type of documentation vary
00797 M01S00797.coding +++| widely, so few rules can be stated; however, Code Level
00798 M01S00798.coding +++| documentation is necessary and the lack of explicit requirements
00799 M01S00799.coding +++| must not lead to its neglect.
00800 M01S00800.coding +++|
00801 M01S00801.coding +++| Code Level documentation, along with the subroutine headings, must
00802 M01S00802.coding +++| satisfy the need for aid in reading the code. Its content follows
00803 M01S00803.coding +++| the guidelines for Detailed Code Analysis in section 2.1.4.
00804 M01S00804.coding +++|
00805 M01S00805.coding +++|
00806 M01S00806.coding +++| 2.5.1 STAND-ALONE COMMENTS
00807 M01S00807.coding +++|
00808 M01S00808.coding +++| Stand-alone comments are comment lines appearing in-line with code,
00809 M01S00809.coding +++| as opposed to within higher-level documentation previously defined.
00810 M01S00810.coding +++| All stand-alone comments are preceded and followed by one blank
00811 M01S00811.coding +++| line. To reduce the binary size of systems texts, stand-alone
00812 M01S00812.coding +++| comments within macro definitions should be preceeded and followed
00813 M01S00813.coding +++| by a blank comment line.
00814 M01S00814.coding +++|
00815 M01S00815.coding +++| Stand-alone comments describe the function performed by the
00816 M01S00816.coding +++| subsequent section of in-line code. The comments are complete
00817 M01S00817.coding +++| English sentences with correct punctuation, ending with a period.
00818 M01S00818.coding +++| The comments refer to functions and data in external terms, rather
00819 M01S00819.coding +++| than only in octal numbers and bit positions. These comments follow
00820 M01S00820.coding +++| the general requirements found in section 2.2.
00821 M01S00821.coding +++|
00822 M01S00822.coding +++|
00823 M01S00823.coding +++| 2.5.2 EMBEDDED COMMENTS
00824 M01S00824.coding +++|
00825 M01S00825.coding +++| Embedded comments are comments in columns 30-71 of a line assembled
00826 M01S00826.coding +++| by COMPASS, not a comment line. The comment need not be a complete
00827 M01S00827.coding +++| sentence and is not terminated with a period. This type of comment
00828 M01S00828.coding +++| is never continued onto another line. If the intended comment is
00829 M01S00829.coding +++| too long to fit on the single line, it is inserted as a stand-alone
00830 M01S00830.coding +++| comment preceding the area of code to which it applies. Care should
00831 M01S00831.coding +++| be taken not to overflow into column 72.
00832 M01S00832.coding +++|
00833 M01S00833.coding +++| An embedded comment describes the function of the instruction or
00834 M01S00834.coding +++| sequence of instructions on which it appears. (It must be at the
00835 M01S00835.coding +++| beginning of the sequence.) It does not describe the hardware
00836 M01S00836.coding +++| operation being performed, but rather its meaning in the context of
00837 M01S00837.coding +++| the function to be performed by the program.
00838 M01S00838.coding +++|
00839 M01S00839.coding +++|1 PAGE 18
00840 M01S00840.coding +++|
00841 M01S00841.coding +++|
00842 M01S00842.coding +++| With the exception of extremely complex code, it should not be
00843 M01S00843.coding +++| necessary to put embedded comments on every line. Frequently, it is
00844 M01S00844.coding +++| advantageous to omit "obvious" or redundent comments, since it then
00845 M01S00845.coding +++| becomes easier for the casual reader to scan the routine.
00846 M01S00846.coding +++|
00847 M01S00847.coding +++| An embedded comment is required on each jump instruction, to
00848 M01S00848.coding +++| identify the condition being tested (conditional jumps) or the
00849 M01S00849.coding +++| action being taken (unconditional jumps). On jump instructions, the
00850 M01S00850.coding +++| word "JUMP" is superfluous, and is not used. On conditional jumps,
00851 M01S00851.coding +++| the comment must begin with the word "IF" and describes the
00852 M01S00852.coding +++| condition on which the jump will be executed. These comments follow
00853 M01S00853.coding +++| the general requirements found in Section 2.2.
00854 M01S00854.coding +++|
00855 M01S00855.coding +++| An embedded comment is required on all pseudo tests (ERRNZ, ERRPL,
00856 M01S00856.coding +++| etc.). The comment should state the condition for which the test
00857 M01S00857.coding +++| fails and the word "IF" should not be used.
00858 M01S00858.coding +++|
00859 M01S00859.coding +++| Example - ERRNG *-BUFAL CODE OVERFLOWS BUFFER AREA
00860 M01S00860.coding +++|
00861 M01S00861.coding +++| 2.6 MACRO LEVEL DOCUMENTATION
00862 M01S00862.coding +++|
00863 M01S00863.coding +++| The heading of any macro definition consists of comment lines giving
00864 M01S00864.coding +++| a brief description of its function, its entry and exit conditions,
00865 M01S00865.coding +++| register or direct cell usage and internal workings. The
00866 M01S00866.coding +++| information contained should be on a level indicated by the
00867 M01S00867.coding +++| complexity of the macro. The following items of data should be
00868 M01S00868.coding +++| included (see section 2.7.4 for the layout of these items):
00869 M01S00869.coding +++|
00870 M01S00870.coding +++| . SPACE line (see section 3.6.3)
00871 M01S00871.coding +++| . Internal comment line giving name and title of macro
00872 M01S00872.coding +++| . One or more lines of text explaining the purpose and/or
00873 M01S00873.coding +++| function of the macro (optional but desirable).
00874 M01S00874.coding +++| . Format of macro call
00875 M01S00875.coding +++| . Entry conditions (list)
00876 M01S00876.coding +++| . Exit conditions (list)
00877 M01S00877.coding +++| . Register or direct cell usage (list)
00878 M01S00878.coding +++| . Routines called (list)
00879 M01S00879.coding +++| . Macros called (list)
00880 M01S00880.coding +++| . Two blank lines
00881 M01S00881.coding +++|
00882 M01S00882.coding +++| Defined formats exist for the list of items in the macro heading.
00883 M01S00883.coding +++| A keyword appears in column 11, followed by text in column 18. The
00884 M01S00884.coding +++| text is simply a list, rather than complete sentences. Any list
00885 M01S00885.coding +++| requiring more than one line is continued beginning in column 18 (or
00886 M01S00886.coding +++| beyond) of the next comment line. The formats are shown below.
00887 M01S00887.coding +++| Each list ends with a period.
00888 M01S00888.coding +++|
00889 M01S00889.coding +++|1 PAGE 19
00890 M01S00890.coding +++|
00891 M01S00891.coding +++|
00892 M01S00892.coding +++| ENTRY Entry conditions.
00893 M01S00893.coding +++| EXIT Exit conditions.
00894 M01S00894.coding +++| USES Register or direct cells destroyed.
00895 M01S00895.coding +++| CALLS Routines called.
00896 M01S00896.coding +++| MACROS Macros called.
00897 M01S00897.coding +++|
00898 M01S00898.coding +++|
00899 M01S00899.coding +++| 2.6.1 ENTRY CONDITIONS (ENTRY)
00900 M01S00900.coding +++|
00901 M01S00901.coding +++| Entry conditions may include the following items:
00902 M01S00902.coding +++|
00903 M01S00903.coding +++| . Description of macro parameters that are allowed. Complete
00904 M01S00904.coding +++| descriptions of macro parameters include:
00905 M01S00905.coding +++| 1. valid parameter options
00906 M01S00906.coding +++| 2. default values of parameters
00907 M01S00907.coding +++| 3. register optimization, if applicable
00908 M01S00908.coding +++|
00909 M01S00909.coding +++| . Registers, direct cells or memory locations that must be
00910 M01S00910.coding +++| set before the macro is called. Entry conditions may refer
00911 M01S00911.coding +++| to the entry documentation found in subroutines called by
00912 M01S00912.coding +++| the macro.
00913 M01S00913.coding +++|
00914 M01S00914.coding +++| . Logical status of channels, files, etc.,(i.e. Channels
00915 M01S00915.coding +++| reserved, files set busy, disk postioned, files positioned)
00916 M01S00916.coding +++| that should exist before the macro is called.
00917 M01S00917.coding +++|
00918 M01S00918.coding +++| Only one entry condition may be specified per line. For PP code,
00919 M01S00919.coding +++| the contents of the A register should be described first.
00920 M01S00920.coding +++|
00921 M01S00921.coding +++|
00922 M01S00922.coding +++| 2.6.2 EXIT CONDITIONS (EXIT)
00923 M01S00923.coding +++|
00924 M01S00924.coding +++| Exit conditions include the following items:
00925 M01S00925.coding +++|
00926 M01S00926.coding +++| . Registers, direct cells or memory locations that may be
00927 M01S00927.coding +++| used by subsequent routines. Exit conditions may refer to
00928 M01S00928.coding +++| exit conditions in subroutines called by the macro.
00929 M01S00929.coding +++|
00930 M01S00930.coding +++| . Logical status of channels, files, etc., (i.e. Channels
00931 M01S00931.coding +++| reserved, files set busy, disk positioned, files postioned)
00932 M01S00932.coding +++| that exist when the code generated by the macro is exited.
00933 M01S00933.coding +++|
00934 M01S00934.coding +++| . Special terminations of the macro such as jumps to error
00935 M01S00935.coding +++| processors or to any other routines. The label being
00936 M01S00936.coding +++| jumped to and the conditions that cause the special exit
00937 M01S00937.coding +++| should be documented.
00938 M01S00938.coding +++|
00939 M01S00939.coding +++| Only one exit condition is listed per line. For PP code, the
00940 M01S00940.coding +++| contents of the A register should be described first.
00941 M01S00941.coding +++|
00942 M01S00942.coding +++|
00943 M01S00943.coding +++|1 PAGE 20
00944 M01S00944.coding +++|
00945 M01S00945.coding +++|
00946 M01S00946.coding +++| 2.6.3 REGISTER OR DIRECT CELL USAGE (USES)
00947 M01S00947.coding +++|
00948 M01S00948.coding +++| Registers or direct cells used include all registers or direct cells
00949 M01S00949.coding +++| destroyed (or modified) by that macro only. Refer to section 2.4.4
00950 M01S00950.coding +++| for the format of the USES block.
00951 M01S00951.coding +++|
00952 M01S00952.coding +++|
00953 M01S00953.coding +++| 2.6.4 ROUTINES CALLED (CALLS)
00954 M01S00954.coding +++|
00955 M01S00955.coding +++| Routines called by a macro include all subroutines and overlays that
00956 M01S00956.coding +++| are explicitly called. Routines called by macros within the macro
00957 M01S00957.coding +++| definition are not to be included.
00958 M01S00958.coding +++|
00959 M01S00959.coding +++|
00960 M01S00960.coding +++| 2.6.5 MACROS CALLED (MACROS)
00961 M01S00961.coding +++|
00962 M01S00962.coding +++| Macros called include all macros that are explicitly called by a
00963 M01S00963.coding +++| macro definition.
00964 M01S00964.coding +++|
00965 M01S00965.coding +++|
00966 M01S00966.coding +++| 2.7 DOCUMENTATION EXAMPLES
00967 M01S00967.coding +++|
00968 M01S00968.coding +++| These examples are statements of the standard and are intended as
00969 M01S00969.coding +++| further clarification of the required procedures.
00970 M01S00970.coding +++|
00971 M01S00971.coding +++|
00972 M01S00972.coding +++| 2.7.1 PROGRAM LEVEL
00973 M01S00973.coding +++|
00974 M01S00974.coding +++| *** LIBEDIT - LIBRARY EDITING PROGRAM.
00975 M01S00975.coding +++| *
00976 M01S00976.coding +++| * A. B. ORIGINAL. 74/01/01.
00977 M01S00977.coding +++| * A. B. MODIFIER. 75/01/01.
00978 M01S00978.coding +++| * C. D. MODIFIER. 76/01/01.
00979 M01S00979.coding +++| SPACE 4,10
00980 M01S00980.coding +++| *** *LIBEDIT* IS A GENERAL PURPOSE FILE EDITING
00981 M01S00981.coding +++| * PROGRAM CAPABLE OF MODIFYING AND GENERATING
00982 M01S00982.coding +++| * LIBRARY FILES.
00983 M01S00983.coding +++| SPACE 4,10
00984 M01S00984.coding +++| *** COMMAND FORMAT.
00985 M01S00985.coding +++| * .
00986 M01S00986.coding +++| * .
00987 M01S00987.coding +++| .
00988 M01S00988.coding +++| SPACE 4,10
00989 M01S00989.coding +++| *** DAYFILE MESSAGES.
00990 M01S00990.coding +++| * .
00991 M01S00991.coding +++| * .
00992 M01S00992.coding +++| .
00993 M01S00993.coding +++|1 PAGE 21
00994 M01S00994.coding +++|
00995 M01S00995.coding +++|
00996 M01S00996.coding +++| SPACE 4,10
00997 M01S00997.coding +++| *** ACCOUNT FILE MESSAGES.
00998 M01S00998.coding +++| * .
00999 M01S00999.coding +++| * .
01000 M01S01000.coding +++| .
01001 M01S01001.coding +++| SPACE 4,10
01002 M01S01002.coding +++| *** ERROR LOG MESSAGES.
01003 M01S01003.coding +++| * .
01004 M01S01004.coding +++| * .
01005 M01S01005.coding +++| .
01006 M01S01006.coding +++| SPACE 4,10
01007 M01S01007.coding +++| *** OPERATOR MESSAGES.
01008 M01S01008.coding +++| * .
01009 M01S01009.coding +++| * .
01010 M01S01010.coding +++| .
01011 M01S01011.coding +++| SPACE 4,10
01012 M01S01012.coding +++| * COMMON DECKS.
01013 M01S01013.coding +++| .
01014 M01S01014.coding +++| .
01015 M01S01015.coding +++| .
01016 M01S01016.coding +++| SPACE 4,10
01017 M01S01017.coding +++| * MACRO DEFINITIONS.
01018 M01S01018.coding +++| .
01019 M01S01019.coding +++| .
01020 M01S01020.coding +++| .
01021 M01S01021.coding +++| **** ASSEMBLY CONSTANTS.
01022 M01S01022.coding +++|
01023 M01S01023.coding +++|
01024 M01S01024.coding +++| BUFL EQU 1001B OUTPUT BUFFER LENGTH
01025 M01S01025.coding +++| ****
01026 M01S01026.coding +++| SPACE 4,10
01027 M01S01027.coding +++| * GLOBAL STORAGE.
01028 M01S01028.coding +++| .
01029 M01S01029.coding +++| .
01030 M01S01030.coding +++| .
01031 M01S01031.coding +++|
01032 M01S01032.coding +++|
01033 M01S01033.coding +++| 2.7.2 SUBROUTINE LEVEL (PP CODE)
01034 M01S01034.coding +++|
01035 M01S01035.coding +++| TITLE ERROR PROCESSING ROUTINES.
01036 M01S01036.coding +++| LEM SPACE 4,30
01037 M01S01037.coding +++| ** LEM - LIST ERROR MESSAGE.
01038 M01S01038.coding +++| *
01039 M01S01039.coding +++| * *LEM* ISSUES ERROR MESSAGES TO THE JOB AND
01040 M01S01040.coding +++| * SYSTEM DAYFILES AND TO THE ERROR LOG.
01041 M01S01041.coding +++| *
01042 M01S01042.coding +++| * ENTRY (A) = 1 IF SINGLE BIT SECDED ERROR.
01043 M01S01043.coding +++| * = 2 IF STATUS/CONTROL REGISTER
01044 M01S01044.coding +++| * ERROR LIMIT.
01045 M01S01045.coding +++|1 PAGE 22
01046 M01S01046.coding +++|
01047 M01S01047.coding +++|
01048 M01S01048.coding +++| * (SCRA - SCRA+20) = SCR IMAGE.
01049 M01S01049.coding +++| * (NL) = ADDRESS OF NEXT LIST ENTRY.
01050 M01S01050.coding +++| *
01051 M01S01051.coding +++| * EXIT (NL) = UPDATED LIST POINTER.
01052 M01S01052.coding +++| *
01053 M01S01053.coding +++| * ERROR TO *ERR* IF ERROR ENCOUNTERED.
01054 M01S01054.coding +++| *
01055 M01S01055.coding +++| * USES T1, T2, CM - CM+4, FN - FN+4.
01056 M01S01056.coding +++| *
01057 M01S01057.coding +++| * CALLS LMC.
01058 M01S01058.coding +++| *
01059 M01S01059.coding +++| * XREF COMPABZ.
01060 M01S01060.coding +++| *
01061 M01S01061.coding +++| * MACROS MONITOR.
01062 M01S01062.coding +++| *
01063 M01S01063.coding +++| * DEFINE (T2) = FWA OF MESSAGE.
01064 M01S01064.coding +++| *
01065 M01S01065.coding +++| * TIMING A DELAY IS NEEDED TO AVOID FILLING THE
01066 M01S01066.coding +++| * DISK WITH ERROR LOG MESSAGES.
01067 M01S01067.coding +++|
01068 M01S01068.coding +++|
01069 M01S01069.coding +++| LEM SUBR ENTRY/EXIT
01070 M01S01070.coding +++| .
01071 M01S01071.coding +++| .
01072 M01S01072.coding +++| .
01073 M01S01073.coding +++| UJN LEMX RETURN
01074 M01S01074.coding +++|
01075 M01S01075.coding +++|
01076 M01S01076.coding +++| 2.7.3 SUBROUTINE LEVEL (CP CODE)
01077 M01S01077.coding +++|
01078 M01S01078.coding +++| ACS SPACE 4,25
01079 M01S01079.coding +++| ** ACS - ASSEMBLE CHARACTER STRING.
01080 M01S01080.coding +++| *
01081 M01S01081.coding +++| * *ACS* ASSEMBLES A CHARACTER STRING INTO BUFFER
01082 M01S01082.coding +++| * *CBUF*, PACKED 10 CHARACTERS PER CM WORD.
01083 M01S01083.coding +++| *
01084 M01S01084.coding +++| * ENTRY (B6) = FWA OF CHARACTER STRING.
01085 M01S01085.coding +++| * (B7) = LENGTH OF STRING BUFFER.
01086 M01S01086.coding +++| *
01087 M01S01087.coding +++| * EXIT (CBUF - CBUF+20) = CHARACTER STRING.
01088 M01S01088.coding +++| *
01089 M01S01089.coding +++| * ERROR TO *ERR* IF INVALID CHARACTER FOUND.
01090 M01S01090.coding +++| * (X1) = FWA OF ERROR MESSAGE.
01091 M01S01091.coding +++| *
01092 M01S01092.coding +++| * USES X - 0, 1, 6.
01093 M01S01093.coding +++| * A - 1, 6.
01094 M01S01094.coding +++| * B - 6, 7.
01095 M01S01095.coding +++| *
01096 M01S01096.coding +++|1 PAGE 23
01097 M01S01097.coding +++|
01098 M01S01098.coding +++|
01099 M01S01099.coding +++| * CALLS MCI.
01100 M01S01100.coding +++| *
01101 M01S01101.coding +++| * MACROS GETCH.
01102 M01S01102.coding +++| *
01103 M01S01103.coding +++| * DEFINE (X0) = CHARACTER MASK.
01104 M01S01104.coding +++|
01105 M01S01105.coding +++|
01106 M01S01106.coding +++| ACS SUBR ENTRY/EXIT
01107 M01S01107.coding +++| .
01108 M01S01108.coding +++| .
01109 M01S01109.coding +++| .
01110 M01S01110.coding +++| EQ ACSX RETURN
01111 M01S01111.coding +++|
01112 M01S01112.coding +++|
01113 M01S01113.coding +++| 2.7.4 MACRO LEVEL DOCUMENTATION
01114 M01S01114.coding +++|
01115 M01S01115.coding +++| ERROR SPACE 4,10
01116 M01S01116.coding +++| ** ERROR - ERROR PROCESSING MACRO.
01117 M01S01117.coding +++| *
01118 M01S01118.coding +++| * ERROR ADDR
01119 M01S01119.coding +++| *
01120 M01S01120.coding +++| * ENTRY *ADDR* = FWA OF DAYFILE MESSAGE.
01121 M01S01121.coding +++| *
01122 M01S01122.coding +++| * EXIT TO *EPR*.
01123 M01S01123.coding +++| *
01124 M01S01124.coding +++| * USES X - 1.
01125 M01S01125.coding +++|
01126 M01S01126.coding +++|
01127 M01S01127.coding +++| PURGMAC ERROR
01128 M01S01128.coding +++|
01129 M01S01129.coding +++| ERROR MACRO A
01130 M01S01130.coding +++| SX1 A
01131 M01S01131.coding +++| EQ EPR
01132 M01S01132.coding +++| ERROR ENDM
01133 M01S01133.coding +++|
01134 M01S01134.coding +++|1 PAGE 24
01135 M01S01135.coding +++|
01136 M01S01136.coding +++|
01137 M01S01137.coding +++| 3.0 CODING
01138 M01S01138.coding +++|
01139 M01S01139.coding +++|
01140 M01S01140.coding +++| 3.1 LINE LAYOUTS
01141 M01S01141.coding +++|
01142 M01S01142.coding +++|
01143 M01S01143.coding +++| 3.1.1 COMPASS OPERATION LINES
01144 M01S01144.coding +++|
01145 M01S01145.coding +++| The following list of column numbers represent the beginning of each
01146 M01S01146.coding +++| field in a COMPASS coding line. (An exception is allowed for macro
01147 M01S01147.coding +++| definitions in system texts where space is critical. Refer to
01148 M01S01148.coding +++| section 3.6.5.)
01149 M01S01149.coding +++|
01150 M01S01150.coding +++| Column 1 = Continuation field (comma) if required
01151 M01S01151.coding +++| Column 2 = Location field
01152 M01S01152.coding +++| Column 11 = Operation field
01153 M01S01153.coding +++| Column 18 = Address field
01154 M01S01154.coding +++| Column 30 = Comment field
01155 M01S01155.coding +++| Column 73-80 = Reserved
01156 M01S01156.coding +++|
01157 M01S01157.coding +++| If a field is full or overflows into an adjacent field, then two
01158 M01S01158.coding +++| spaces should separate the fields. For readability, a block of
01159 M01S01159.coding +++| comments can be aligned in a column past column 30. Column 72 of
01160 M01S01160.coding +++| the comment field should be blank unless a continuation line is
01161 M01S01161.coding +++| required.
01162 M01S01162.coding +++|
01163 M01S01163.coding +++| 3.1.2 COMPASS COMMENT LINES
01164 M01S01164.coding +++|
01165 M01S01165.coding +++| The following list of column numbers represent the format of a
01166 M01S01166.coding +++| comment line. A full description of where and how to use comment
01167 M01S01167.coding +++| lines is found in section 2.
01168 M01S01168.coding +++|
01169 M01S01169.coding +++| Column 1 = always contains an asterisk
01170 M01S01170.coding +++| Column 2-5 = (see section 2.2.3)
01171 M01S01171.coding +++| Column 6-10 = generally blank
01172 M01S01172.coding +++| Column 11-71 = contains the text of the comment
01173 M01S01173.coding +++| Column 72-80 = reserved
01174 M01S01174.coding +++|
01175 M01S01175.coding +++|
01176 M01S01176.coding +++| 3.2 PROGRAM LAYOUT
01177 M01S01177.coding +++|
01178 M01S01178.coding +++| The following sections define the components of a program in the
01179 M01S01179.coding +++| order they appear within the program. It is not expected or
01180 M01S01180.coding +++| required that every program will consist of all components
01181 M01S01181.coding +++| described. In this discussion a "program" is a relocatable program
01182 M01S01182.coding +++| unit (from "IDENT" to "END"), an entire absolute program or a common
01183 M01S01183.coding +++| deck. A subroutine is a routine within a program.
01184 M01S01184.coding +++|
01185 M01S01185.coding +++|
01186 M01S01186.coding +++|1 PAGE 25
01187 M01S01187.coding +++|
01188 M01S01188.coding +++|
01189 M01S01189.coding +++| 3.2.1 GROUP 1 INSTRUCTIONS
01190 M01S01190.coding +++|
01191 M01S01191.coding +++| Group 1 instructions appear at the beginning of each program and
01192 M01S01192.coding +++| contain the identification and environment information for the
01193 M01S01193.coding +++| program. The following examples define the layout of the Group 1
01194 M01S01194.coding +++| instructions for each type of program.
01195 M01S01195.coding +++|
01196 M01S01196.coding +++|
01197 M01S01197.coding +++| 3.2.1.1 PERIPHERAL PROCESSOR PROGRAMS
01198 M01S01198.coding +++|
01199 M01S01199.coding +++| 1 11 18 30 (Columns)
01200 M01S01200.coding +++| +---------+------+-----------+-----
01201 M01S01201.coding +++|
01202 M01S01202.coding +++| IDENT XXX,ORIGIN
01203 M01S01203.coding +++| MACHINE (optional)
01204 M01S01204.coding +++| PERIPH
01205 M01S01205.coding +++| NOLABEL (deadstart routines)
01206 M01S01206.coding +++| BASE M
01207 M01S01207.coding +++| LIST (optional)
01208 M01S01208.coding +++| SST
01209 M01S01209.coding +++| TITLE XXX - program description.
01210 M01S01210.coding +++| *COMMENT deckname - description.
| Line S01211 Modification History |
M01 (Added by) | coding |
M02 (Updated by) | 281l803 |
Seq # *Modification Id* Act
----------------------------+
01211 M02S01211.281l803 ---| COMMENT COPYRIGHT CONTROL DATA CORPORATION, year.
01212 M01S00001.281l803 +++| COMMENT COPYRIGHT CONTROL DATA SYSTEMS INC. year.
01213 M01S01212.coding +++| XXX SPACE 4,10
01214 M01S01213.coding +++|
01215 M01S01214.coding +++|
01216 M01S01215.coding +++| 3.2.1.2 CENTRAL PROCESSOR PROGRAMS
01217 M01S01216.coding +++|
01218 M01S01217.coding +++|
01219 M01S01218.coding +++| IDENT XXXXXXX,FWA program description
01220 M01S01219.coding +++| ABS (optional)
01221 M01S01220.coding +++| MACHINE (optional)
01222 M01S01221.coding +++| LCC (optional)
01223 M01S01222.coding +++| SST (optional)
01224 M01S01223.coding +++| ENTRY YYYY (optional)
01225 M01S01224.coding +++| SYSCOM B1
01226 M01S01225.coding +++| LIST (optional)
01227 M01S01226.coding +++| TITLE XXXXXXX - program description.
01228 M01S01227.coding +++| *COMMENT deckname - description.
| Line S01228 Modification History |
M01 (Added by) | coding |
M02 (Updated by) | 281l803 |
Seq # *Modification Id* Act
----------------------------+
01229 M02S01228.281l803 ---| COMMENT COPYRIGHT CONTROL DATA CORPORATION, year.
01230 M01S00002.281l803 +++| COMMENT COPYRIGHT CONTROL DATA SYSTEMS INC. year.
01231 M01S01229.coding +++| XXX SPACE 4,10
01232 M01S01230.coding +++|
01233 M01S01231.coding +++|
01234 M01S01232.coding +++|1 PAGE 26
01235 M01S01233.coding +++|
01236 M01S01234.coding +++|
01237 M01S01235.coding +++| 3.2.1.3 COMMON DECKS
01238 M01S01236.coding +++|
01239 M01S01237.coding +++| 1 11 18 30 (Columns)
01240 M01S01238.coding +++| +---------+------+-----------+-----
01241 M01S01239.coding +++|
01242 M01S01240.coding +++| CTEXT XXXXXXX - common deck description.
01243 M01S01241.coding +++| SPACE 4,10
01244 M01S01242.coding +++| QUAL$ IF -DEF,QUAL$
01245 M01S01243.coding +++| QUAL XXXXXXX
01246 M01S01244.coding +++| QUAL$ ENDIF
01247 M01S01245.coding +++| BASE B (B = any legal value)
01248 M01S01246.coding +++| CODE C (optional)
| Line S01247 Modification History |
M01 (Added by) | coding |
M02 (Updated by) | 281l803 |
Seq # *Modification Id* Act
----------------------------+
01249 M02S01247.281l803 ---| * COMMENT COPYRIGHT CONTROL DATA CORPORATION, year.
01250 M01S00003.281l803 +++| * COMMENT COPYRIGHT CONTROL DATA SYSTEMS INC. year.
01251 M01S01248.coding +++| XXX SPACE 4,10
01252 M01S01249.coding +++|
01253 M01S01250.coding +++| Refer to section 4.4.3 for further information on qualification of
01254 M01S01251.coding +++| common decks.
01255 M01S01252.coding +++|
01256 M01S01253.coding +++|
01257 M01S01254.coding +++| 3.2.2 PROGRAM LEVEL DOCUMENTATION
01258 M01S01255.coding +++|
01259 M01S01256.coding +++| Program level documentation consists of overview, external and
01260 M01S01257.coding +++| internal documentation as described in section 2.3.
01261 M01S01258.coding +++|
01262 M01S01259.coding +++|
01263 M01S01260.coding +++| 3.2.3 MACRO DEFINITIONS
01264 M01S01261.coding +++|
01265 M01S01262.coding +++| The macros are in alphabetical order. Common decks which define
01266 M01S01263.coding +++| macros should be included before local macro definitions in
01267 M01S01264.coding +++| alphabetical order.
01268 M01S01265.coding +++|
01269 M01S01266.coding +++|
01270 M01S01267.coding +++| 3.2.4 INSTALLATION SYMBOL DEFINITIONS
01271 M01S01268.coding +++|
01272 M01S01269.coding +++| Installation symbols are parameters that may be changed by a site
01273 M01S01270.coding +++| when installing a product. These symbols may include buffer
01274 M01S01271.coding +++| lengths, default values, and timing delays. Installation symbols
01275 M01S01272.coding +++| are defined in alphabetical order unless functional order is more
01276 M01S01273.coding +++| meaningful. The installation symbol definition area should be
01277 M01S01274.coding +++| bracketed by internal bracket lines (****).
01278 M01S01275.coding +++|
01279 M01S01276.coding +++|
01280 M01S01277.coding +++| 3.2.5 LOCAL SYMBOL DEFINITIONS
01281 M01S01278.coding +++|
01282 M01S01279.coding +++| Local symbols are parameters that should not be changed by an
01283 M01S01280.coding +++| installation. These symbols may include code generation symbols
01284 M01S01281.coding +++| (QUAL$, DBI$, etc.) And symbols used for cross reference purposes.
01285 M01S01282.coding +++| Local symbols are defined in alphabetical order, unless
01286 M01S01283.coding +++| functional order is more meaningful.
01287 M01S01284.coding +++|
01288 M01S01285.coding +++|
01289 M01S01286.coding +++|1 PAGE 27
01290 M01S01287.coding +++|
01291 M01S01288.coding +++|
01292 M01S01289.coding +++| 3.2.6 GLOBAL MEMORY DEFINITIONS
01293 M01S01290.coding +++|
01294 M01S01291.coding +++| This section of the program is used to define memory that is preset
01295 M01S01292.coding +++| with data. This section may include FETs, tables, and working
01296 M01S01293.coding +++| storage. Global memory definitions are defined in alphabetical
01297 M01S01294.coding +++| order unless functional order is more meaningful.
01298 M01S01295.coding +++|
01299 M01S01296.coding +++|
01300 M01S01297.coding +++| 3.2.7 MAIN LOOP
01301 M01S01298.coding +++|
01302 M01S01299.coding +++| This section of the program contains the major logic and control
01303 M01S01300.coding +++| flow for the program and internal documentation for that flow (see
01304 M01S01301.coding +++| section 2.4). A TITLE line with an appropriate subtitle precedes
01305 M01S01302.coding +++| the first primary subroutine.
01306 M01S01303.coding +++|
01307 M01S01304.coding +++|
01308 M01S01305.coding +++| 3.2.8 PRIMARY SUBROUTINES
01309 M01S01306.coding +++|
01310 M01S01307.coding +++| This section of the program contains the subroutines which are of
01311 M01S01308.coding +++| major importance to the program. They should be in alphabetical
01312 M01S01309.coding +++| order unless there is a logically associated set of subroutines
01313 M01S01310.coding +++| which interact together (in which case these subroutines may be
01314 M01S01311.coding +++| grouped together). Each subroutine contains documentation as
01315 M01S01312.coding +++| described in section 2.4. A TITLE line with an appropriate subtitle
01316 M01S01313.coding +++| precedes the first primary subroutine.
01317 M01S01314.coding +++|
01318 M01S01315.coding +++|
01319 M01S01316.coding +++| 3.2.9 SECONDARY SUBROUTINES
01320 M01S01317.coding +++|
01321 M01S01318.coding +++| This section of the program contains subroutines of minor importance
01322 M01S01319.coding +++| to the program. They should be in alphabetical order unless there
01323 M01S01320.coding +++| is a logically associated set of subroutines which interact together
01324 M01S01321.coding +++| (in which case these subroutines may be grouped together). A TITLE
01325 M01S01322.coding +++| line with an appropriate subtitle precedes the first secondary
01326 M01S01323.coding +++| subroutine. Each subroutine contains documentation as described in
01327 M01S01324.coding +++| section 2.4.
01328 M01S01325.coding +++|
01329 M01S01326.coding +++| Common decks (except those used for initialization) are after the
01330 M01S01327.coding +++| secondary subroutines. Common decks should be listed in
01331 M01S01328.coding +++| alphabetical order whenever possible.
01332 M01S01329.coding +++|
01333 M01S01330.coding +++|
01334 M01S01331.coding +++| 3.2.10 WORKING STORAGE AND BUFFERS
01335 M01S01332.coding +++|
01336 M01S01333.coding +++| This section of the program contains working storage and buffer
01337 M01S01334.coding +++| definitions that are not preset with data. (Refer to section 3.4.5)
01338 M01S01335.coding +++| Use of EQU or BSSN is preferred to BSS since additional code is not
01339 M01S01336.coding +++| added to the binary.
01340 M01S01337.coding +++|
01341 M01S01338.coding +++| 3.2.11 INITIALIZATION CODE
01342 M01S01339.coding +++|
01343 M01S01340.coding +++| Code which may be overlayed after program initialization is included
01344 M01S01341.coding +++| here.
01345 M01S01342.coding +++|
01346 M01S01343.coding +++|
01347 M01S01344.coding +++|1 PAGE 28
01348 M01S01345.coding +++|
01349 M01S01346.coding +++|
01350 M01S01347.coding +++| 3.2.12 PROGRAM TERMINATION
01351 M01S01348.coding +++|
01352 M01S01349.coding +++| All programs end with an "END" statement except common decks which
01353 M01S01350.coding +++| end as follows:
01354 M01S01351.coding +++|
01355 M01S01352.coding +++| 1 11 18 30 (columns)
01356 M01S01353.coding +++| +---------+------+-----------+-----
01357 M01S01354.coding +++|
01358 M01S01355.coding +++| BASE * (if applicable)
01359 M01S01356.coding +++| CODE * (if applicable)
01360 M01S01357.coding +++| QUAL$ IF -DEF,QUAL$
01361 M01S01358.coding +++| QUAL *
01362 M01S01359.coding +++| YYY EQU /XXXXXXX/YYY (unqualified entry point)
01363 M01S01360.coding +++| .
01364 M01S01361.coding +++| .
01365 M01S01362.coding +++| .
01366 M01S01363.coding +++| QUAL$ ENDIF
01367 M01S01364.coding +++| XXX ENDX
01368 M01S01365.coding +++|
01369 M01S01366.coding +++| If "CODE x" is used at the beginning but "CODE *" is not used at the
01370 M01S01367.coding +++| end of a common deck, it must be explicitly documented in the common
01371 M01S01368.coding +++| deck header.
01372 M01S01369.coding +++|
01373 M01S01370.coding +++| If the main listing title has been changed by use of an IDENT or TTL
01374 M01S01371.coding +++| line, the main title must be restored with a TTL line just before
01375 M01S01372.coding +++| the END line to provide the correct title on the symbolic reference
01376 M01S01373.coding +++| table.
01377 M01S01374.coding +++|
01378 M01S01375.coding +++|
01379 M01S01376.coding +++| 3.3 INSTRUCTION USE, FORMAT, AND PARAMETERS
01380 M01S01377.coding +++|
01381 M01S01378.coding +++|
01382 M01S01379.coding +++| 3.3.1 REGISTER USE AND SPECIFICATION
01383 M01S01380.coding +++|
01384 M01S01381.coding +++|
01385 M01S01382.coding +++| 3.3.1.1 B0 REGISTER USE
01386 M01S01383.coding +++|
01387 M01S01384.coding +++| The B0 register should not be specified in instructions which test B
01388 M01S01385.coding +++| registers. The assembler assumes B0 if the requisite number of B
01389 M01S01386.coding +++| registers is not specified.
01390 M01S01387.coding +++|
01391 M01S01388.coding +++|
01392 M01S01389.coding +++| 3.3.1.2 B1 REGISTER USE
01393 M01S01390.coding +++|
01394 M01S01391.coding +++| The B1 register must always contain the value one (1). The "SYSCOM
01395 M01S01392.coding +++| B1" macro is included in each program to indicate that B1 will
01396 M01S01393.coding +++| contain this value. B1 must be set to 1 immediately upon program
01397 M01S01394.coding +++| entry. B1 is then used by COMPASS in conjunction with the R= psuedo
01398 M01S01395.coding +++| instruction to generate 15 bit instructions rather than 30 bit
01399 M01S01396.coding +++| instructions.
01400 M01S01397.coding +++|
01401 M01S01398.coding +++|1 PAGE 29
01402 M01S01399.coding +++|
01403 M01S01400.coding +++|
01404 M01S01401.coding +++| It should be assumed that calls to external entry points which may
01405 M01S01402.coding +++| be loaded from an external source destroy B1. Therefore, B1 should
01406 M01S01403.coding +++| be reset to one after these calls.
01407 M01S01404.coding +++|
01408 M01S01405.coding +++|
01409 M01S01406.coding +++| 3.3.1.3 PACK AND NOMINAL SHIFT X REGISTERS
01410 M01S01407.coding +++|
01411 M01S01408.coding +++| In the Pack and Nominal Shift instructions, the X register is
01412 M01S01409.coding +++| specified before the B register, as follows:
01413 M01S01410.coding +++|
01414 M01S01411.coding +++| PXi Xk,Bj
01415 M01S01412.coding +++|
01416 M01S01413.coding +++| LXi Xk,Bj
01417 M01S01414.coding +++|
01418 M01S01415.coding +++|
01419 M01S01416.coding +++| 3.3.1.4 UNPACK AND NORMALIZE X REGISTERS
01420 M01S01417.coding +++|
01421 M01S01418.coding +++| In the Unpack and Normalize instructions, the B register is
01422 M01S01419.coding +++| specified in the opcode field immediately following the opcode.
01423 M01S01420.coding +++|
01424 M01S01421.coding +++| UXi,Bj Xk
01425 M01S01422.coding +++|
01426 M01S01423.coding +++| NXi,Bj Xk
01427 M01S01424.coding +++|
01428 M01S01425.coding +++|
01429 M01S01426.coding +++| 3.3.2 MULTIPLE LOGICAL TESTS
01430 M01S01427.coding +++|
01431 M01S01428.coding +++| When a PP program tests a value in the A-register for equality with
01432 M01S01429.coding +++| several possible values, it may be done with a sequence of logical
01433 M01S01430.coding +++| difference (exclusive "or") operations, as follows:
01434 M01S01431.coding +++|
01435 M01S01432.coding +++| LMC AA
01436 M01S01433.coding +++| ZJN XYZ12 IF TYPE AA
01437 M01S01434.coding +++| LMC BB^AA
01438 M01S01435.coding +++| ZJN XYZ24 IF TYPE BB
01439 M01S01436.coding +++| LMC CC^BB
01440 M01S01437.coding +++| ZJN XYZ36 IF TYPE CC
01441 M01S01438.coding +++|
01442 M01S01439.coding +++| The value being tested is specified first in the LMC.
01443 M01S01440.coding +++|
01444 M01S01441.coding +++| Alternatively, a table look-up may be more efficient.
01445 M01S01442.coding +++|
01446 M01S01443.coding +++|
01447 M01S01444.coding +++| 3.3.3 SHIFT INSTRUCTION PARAMETERS
01448 M01S01445.coding +++|
01449 M01S01446.coding +++| Shift counts in shift instructions which are used to test bits, are
01450 M01S01447.coding +++| coded in one of the following forms:
01451 M01S01448.coding +++|
01452 M01S01449.coding +++| A-B (first shift of a word)
01453 M01S01450.coding +++|
01454 M01S01451.coding +++| A-B-AA+BB+M (next shift of the word)
01455 M01S01452.coding +++|
01456 M01S01453.coding +++|1 PAGE 30
01457 M01S01454.coding +++|
01458 M01S01455.coding +++|
01459 M01S01456.coding +++| Where:
01460 M01S01457.coding +++|
01461 M01S01458.coding +++| A = The desired position of a bit in the word.
01462 M01S01459.coding +++| B = The original position of a bit in the word (before any
01463 M01S01460.coding +++| shifts).
01464 M01S01461.coding +++| AA,BB= The A and B parameters from the previous shift of
01465 M01S01462.coding +++| this word.
01466 M01S01463.coding +++| M = Modulus value
01467 M01S01464.coding +++|
01468 M01S01465.coding +++| Note: The modulus values (60 for CPU and 22B for PP) may have to
01469 M01S01466.coding +++| be added to the shift value if the resulting value is not
01470 M01S01467.coding +++| within the legal limits for the instruction.
01471 M01S01468.coding +++|
01472 M01S01469.coding +++| Example:
01473 M01S01470.coding +++|
01474 M01S01471.coding +++| 1. To shift bit 47 to bit 59:
01475 M01S01472.coding +++|
01476 M01S01473.coding +++| LXi 59-47
01477 M01S01474.coding +++|
01478 M01S01475.coding +++| 2. To shift the result of example 1 so that bit 32 of the original
01479 M01S01476.coding +++| register (before any shifts) is in bit 59 of the result:
01480 M01S01477.coding +++|
01481 M01S01478.coding +++| LXi 59-32-59+47
01482 M01S01479.coding +++|
01483 M01S01480.coding +++| 3. To shift the result of example 2 so that bit 58 of the original
01484 M01S01481.coding +++| register (before any shifts) is in bit 59 of the result:
01485 M01S01482.coding +++|
01486 M01S01483.coding +++| LXi 59-58-59+32
01487 M01S01484.coding +++|
01488 M01S01485.coding +++| Example:
01489 M01S01486.coding +++|
01490 M01S01487.coding +++| 1. To shift bit 2 to bit 21B:
01491 M01S01488.coding +++|
01492 M01S01489.coding +++| SHN 21-2
01493 M01S01490.coding +++|
01494 M01S01491.coding +++| 2. To shift the result of example 1 so that bit 5 of the original
01495 M01S01492.coding +++| register (before any shift) is in bit 21 of the result:
01496 M01S01493.coding +++|
01497 M01S01494.coding +++| SHN 21-5-21+2+22
01498 M01S01495.coding +++|
01499 M01S01496.coding +++| A modulus of 22B is needed in this case to avoid executing a right
01500 M01S01497.coding +++| shift (ie. The resultant shift would otherwise be negative.)
01501 M01S01498.coding +++|
01502 M01S01499.coding +++|
01503 M01S01500.coding +++|1 PAGE 31
01504 M01S01501.coding +++|
01505 M01S01502.coding +++|
01506 M01S01503.coding +++| 3.3.4 BOOLEAN MASK USAGE
01507 M01S01504.coding +++|
01508 M01S01505.coding +++| The mask created for use in boolean instructions depends on whether
01509 M01S01506.coding +++| the field of bits to be extracted is in the left or right hand part
01510 M01S01507.coding +++| of the word. If the field of n bits is in the left hand part of the
01511 M01S01508.coding +++| word, use the following method:
01512 M01S01509.coding +++|
01513 M01S01510.coding +++| MXi n
01514 M01S01511.coding +++| BXj Xi*Xk (Xj contains the extracted field)
01515 M01S01512.coding +++|
01516 M01S01513.coding +++| If the field of n bits is in the right hand part of the word, the
01517 M01S01514.coding +++| following method is used:
01518 M01S01515.coding +++|
01519 M01S01516.coding +++| MXi -n
01520 M01S01517.coding +++| BXj -Xi*Xk (Xj contains the extracted field)
01521 M01S01518.coding +++|
01522 M01S01519.coding +++| If the mask is used in more than one way, the first use determines
01523 M01S01520.coding +++| how it is defined.
01524 M01S01521.coding +++|
01525 M01S01522.coding +++|
01526 M01S01523.coding +++| 3.3.5 RELATIVE ADDRESSING
01527 M01S01524.coding +++|
01528 M01S01525.coding +++| Relative addressing (such as *+n and *-n, where n is a numeric
01529 M01S01526.coding +++| value) should not be used except:
01530 M01S01527.coding +++|
01531 M01S01528.coding +++| 1. In timing delays (where *-1 is the only acceptable value).
01532 M01S01529.coding +++| 2. For instruction modification (where *-1 or *-2 are the only
01533 M01S01530.coding +++| acceptable values).
01534 M01S01531.coding +++| 3. In PP code to reference bytes within a CPU word. The relative
01535 M01S01532.coding +++| address must be in one of the following forms:
01536 M01S01533.coding +++|
01537 M01S01534.coding +++| tag+n
01538 M01S01535.coding +++| tag+c*5+n
01539 M01S01536.coding +++|
01540 M01S01537.coding +++| where:
01541 M01S01538.coding +++|
01542 M01S01539.coding +++| tag = base address
01543 M01S01540.coding +++| c = CM word within the PP buffer
01544 M01S01541.coding +++| n = byte within the CM word (0 - 4)
01545 M01S01542.coding +++|
01546 M01S01543.coding +++|
01547 M01S01544.coding +++| 3.3.6 JUMP INSTRUCTION USE
01548 M01S01545.coding +++|
01549 M01S01546.coding +++| Unconditional jumps in CPU code are coded using the EQ instruction
01550 M01S01547.coding +++| so that the instruction stack is not voided. When it is necessary
01551 M01S01548.coding +++| to void the instruction stack the RJ instruction is used. (The RJ
01552 M01S01549.coding +++| is the only instruction which voids the stack on all central
01553 M01S01550.coding +++| processors.)
01554 M01S01551.coding +++|
01555 M01S01552.coding +++| PP jump macros MJP, NJP, PJP, UJP, ZJP can be used to assemble short
01556 M01S01553.coding +++| or long jump as needed; however, these macros should be avoided when
01557 M01S01554.coding +++| branching forward since a long jump sequence is always generated if
01558 M01S01555.coding +++| the jump address has not yet been defined on pass 1 of the assembly.
01559 M01S01556.coding +++|
01560 M01S01557.coding +++|1 PAGE 32
01561 M01S01558.coding +++|
01562 M01S01559.coding +++|
01563 M01S01560.coding +++| A blank line is inserted after each unconditional jump instruction
01564 M01S01561.coding +++| to indicate a break in the program flow. If the unconditional jump
01565 M01S01562.coding +++| occurs at the end of a subroutine, a SPACE line or TITLE line may be
01566 M01S01563.coding +++| used.
01567 M01S01564.coding +++|
01568 M01S01565.coding +++| A blank line is also required after an implied unconditional jump.
01569 M01S01566.coding +++| The following are examples of an implied unconditional jump.
01570 M01S01567.coding +++|
01571 M01S01568.coding +++| Example:
01572 M01S01569.coding +++|
01573 M01S01570.coding +++| A blank line should be inserted after macro calls that break the
01574 M01S01571.coding +++| flow of execution in a sequence of code.
01575 M01S01572.coding +++|
01576 M01S01573.coding +++| .
01577 M01S01574.coding +++| .
01578 M01S01575.coding +++| .
01579 M01S01576.coding +++| NZ X1,tag2 IF comment
01580 M01S01577.coding +++| ABORT TERMINATE
01581 M01S01578.coding +++| (blank line)
01582 M01S01579.coding +++| tag2 SA1 B2
01583 M01S01580.coding +++| .
01584 M01S01581.coding +++| .
01585 M01S01582.coding +++| .
01586 M01S01583.coding +++|
01587 M01S01584.coding +++| Example:
01588 M01S01585.coding +++|
01589 M01S01586.coding +++| When code occurs before the SUBR, there should be a blank line
01590 M01S01587.coding +++| between the code and the SUBR.
01591 M01S01588.coding +++|
01592 M01S01589.coding +++| tag2 LDN 0 comment
01593 M01S01590.coding +++| (blank line)
01594 M01S01591.coding +++| tag SUBR ENTRY/EXIT
01595 M01S01592.coding +++| .
01596 M01S01593.coding +++| tag1 .
01597 M01S01594.coding +++| .
01598 M01S01595.coding +++| UJN tagX RETURN
01599 M01S01596.coding +++|
01600 M01S01597.coding +++|
01601 M01S01598.coding +++| tagA BSS 1 comment
01602 M01S01599.coding +++|
01603 M01S01600.coding +++| When storage locations for a subroutine are defined at the end of
01604 M01S01601.coding +++| the routine, there should be 2 blank lines between the code and the
01605 M01S01602.coding +++| first data tag.
01606 M01S01603.coding +++|
01607 M01S01604.coding +++| 3.3.7 SUBROUTINE ENTRY
01608 M01S01605.coding +++|
01609 M01S01606.coding +++| Each subroutine has one and only one entry point. Exceptions are
01610 M01S01607.coding +++| allowed as follows:
01611 M01S01608.coding +++|
01612 M01S01609.coding +++| If memory limitations in a PP program make this impractical.
01613 M01S01610.coding +++|
01614 M01S01611.coding +++| For termination subroutines (such as error processors). Each
01615 M01S01612.coding +++| entry point should be documented within the subroutine.
01616 M01S01613.coding +++|
01617 M01S01614.coding +++|1 PAGE 33
01618 M01S01615.coding +++|
01619 M01S01616.coding +++|
01620 M01S01617.coding +++| PP and CPU subroutines which are entered via a return jump contain
01621 M01S01618.coding +++| the following instruction at their entry/exit point:
01622 M01S01619.coding +++|
01623 M01S01620.coding +++| tag SUBR ENTRY/EXIT
01624 M01S01621.coding +++| .
01625 M01S01622.coding +++| .
01626 M01S01623.coding +++| .
01627 M01S01624.coding +++| UJN tagX RETURN
01628 M01S01625.coding +++|
01629 M01S01626.coding +++| or,
01630 M01S01627.coding +++|
01631 M01S01628.coding +++| tag SUBR ENTRY/EXIT
01632 M01S01629.coding +++| .
01633 M01S01630.coding +++| .
01634 M01S01631.coding +++| .
01635 M01S01632.coding +++| EQ tagX RETURN
01636 M01S01633.coding +++|
01637 M01S01634.coding +++|
01638 M01S01635.coding +++| A subroutine may also consist of a block of code that is entered by
01639 M01S01636.coding +++| a jump instruction. In this case, the subroutine entry points
01640 M01S01637.coding +++| should be clearly documented using a BSS pseudo-instruction:
01641 M01S01638.coding +++|
01642 M01S01639.coding +++| TAG BSS 0 ENTRY
01643 M01S01640.coding +++| .
01644 M01S01641.coding +++| .
01645 M01S01642.coding +++| .
01646 M01S01643.coding +++|
01647 M01S01644.coding +++| Subroutines defined with SUBR should be used for hangs and error
01648 M01S01645.coding +++| processors so the RJ/RJM for CP/PP code leaves a trace of the
01649 M01S01646.coding +++| caller, even though return to the caller is not used. PP's should
01650 M01S01647.coding +++| write the caller's address and other pertinent information in the PP
01651 M01S01648.coding +++| output register or message buffer (space permitting) before issuing
01652 M01S01649.coding +++| a HNGM monitor function.
01653 M01S01650.coding +++|
01654 M01S01651.coding +++| 3.3.8 CPU CODE OPTIMIZATION
01655 M01S01652.coding +++|
01656 M01S01653.coding +++| An effort should be made to avoid the generation of NO-OPs at the
01657 M01S01654.coding +++| end of a 60-bit word. This may be done by arrangement of code so
01658 M01S01655.coding +++| that each 60-bit word is completely filled with executable code.
01659 M01S01656.coding +++| This is also done for instructions which have an optional "k"
01660 M01S01657.coding +++| parameter by supplying a zero value for "k", thus generating a 30-
01661 M01S01658.coding +++| bit instruction instead of a 15-bit instruction. The way to do this
01662 M01S01659.coding +++| is to append a "+" to the register in the variable field of
01663 M01S01660.coding +++| the instruction, as shown below:
01664 M01S01661.coding +++|
01665 M01S01662.coding +++| SA4 A1+ (Generates 30-bit instruction)
01666 M01S01663.coding +++|
01667 M01S01664.coding +++| This indicates that the padding was added for optimization purposes
01668 M01S01665.coding +++| and may be removed as necessary when the code is modified.
01669 M01S01666.coding +++|1 PAGE 34
01670 M01S01667.coding +++|
01671 M01S01668.coding +++|
01672 M01S01669.coding +++| When initializing an X register to zero, a
01673 M01S01670.coding +++|
01674 M01S01671.coding +++| SXi B0+
01675 M01S01672.coding +++|
01676 M01S01673.coding +++| should be used if a 30 bit instruction packs better.
01677 M01S01674.coding +++|
01678 M01S01675.coding +++| If a 15 bit instruction packs better,
01679 M01S01676.coding +++|
01680 M01S01677.coding +++| BXi Xi-Xi
01681 M01S01678.coding +++|
01682 M01S01679.coding +++| is preferred; but for efficiency
01683 M01S01680.coding +++|
01684 M01S01681.coding +++| SXi B0
01685 M01S01682.coding +++| MXi 0
01686 M01S01683.coding +++|
01687 M01S01684.coding +++| also may be used interchangeably.
01688 M01S01685.coding +++|
01689 M01S01686.coding +++|
01690 M01S01687.coding +++| 3.3.9 CLEARING PP MEMORY
01691 M01S01688.coding +++|
01692 M01S01689.coding +++| The following coding sequence is used to clear 5 consecutive words
01693 M01S01690.coding +++| of PP memory to zeroes:
01694 M01S01691.coding +++|
01695 M01S01692.coding +++| LDN ZERL
01696 M01S01693.coding +++| CRD tag
01697 M01S01694.coding +++|
01698 M01S01695.coding +++| The constant ZERL should not be assumed to be at address absolute
01699 M01S01696.coding +++| zero in memory.
01700 M01S01697.coding +++|
01701 M01S01698.coding +++|
01702 M01S01699.coding +++| 3.3.10 INSTRUCTION MODIFICATION
01703 M01S01700.coding +++|
01704 M01S01701.coding +++| Instruction modification greatly increases the complexity of code
01705 M01S01702.coding +++| and is a reliable source of program errors. It is a practice to be
01706 M01S01703.coding +++| avoided wherever possible. The sole justification for instruction
01707 M01S01704.coding +++| modification is overwhelming space or time-critical constraint, such
01708 M01S01705.coding +++| as a crowded PP, an in-stack loop, or a hardware driver. It is
01709 M01S01706.coding +++| particularly important that one routine modifying the contents of
01710 M01S01707.coding +++| another routine be avoided. It is far preferable to employ a global
01711 M01S01708.coding +++| variable for communications between routines, even at the expense of
01712 M01S01709.coding +++| some storage.
01713 M01S01710.coding +++|
01714 M01S01711.coding +++| Where a routine must modify code within another routine, the
01715 M01S01712.coding +++| modified code must be documented as an EXIT condition from the first
01716 M01S01713.coding +++| routine and an ENTRY condition to the second.
01717 M01S01714.coding +++|
01718 M01S01715.coding +++| Data locations imbedded within a routine and referenced by more than
01719 M01S01716.coding +++| one routine should be assigned descriptive, global variable symbols
01720 M01S01717.coding +++| (this is an exception to the standard for the naming of data
01721 M01S01718.coding +++| locations within a routine). This will somewhat decrease the
01722 M01S01719.coding +++| chances of error arising from their use.
01723 M01S01720.coding +++|
01724 M01S01721.coding +++|1 PAGE 35
01725 M01S01722.coding +++|
01726 M01S01723.coding +++|
01727 M01S01724.coding +++| Instructions which must be modified are to be followed by a comment
01728 M01S01725.coding +++| which shows each alternative form under which the instruction can
01729 M01S01726.coding +++| take. The following examples show the layout used:
01730 M01S01727.coding +++|
01731 M01S01728.coding +++| Example:
01732 M01S01729.coding +++|
01733 M01S01730.coding +++| tag LDC TRCO SET READ FUNCTION
01734 M01S01731.coding +++| * LDC TWTO (WRITE FUNCTION)
01735 M01S01732.coding +++| * LDC TFCN (POSITION FUNCTION)
01736 M01S01733.coding +++| tagA EQU *-1
01737 M01S01734.coding +++|
01738 M01S01735.coding +++| Example:
01739 M01S01736.coding +++|
01740 M01S01737.coding +++| tagA LDC * RESTORE (T1)
01741 M01S01738.coding +++| * LDC (T1) (CONTENTS OF T1)
01742 M01S01739.coding +++| STD T1
01743 M01S01740.coding +++|
01744 M01S01741.coding +++| The comment in ( ) should describe the conditions under which the
01745 M01S01742.coding +++| instruction is changed.
01746 M01S01743.coding +++|
01747 M01S01744.coding +++| In CPU code, care must be taken to insure that the instruction being
01748 M01S01745.coding +++| modified is not already in the instruction stack. Since the only
01749 M01S01746.coding +++| way to guarantee this for all mainframes is to perform an RJ
01750 M01S01747.coding +++| instruction, any CPU program that does code modification must have
01751 M01S01748.coding +++| at least one RJ instruction between the modification and the
01752 M01S01749.coding +++| execution of the code. This RJ may be a call to a dummy subroutine,
01753 M01S01750.coding +++| or to a "normal" one; if a call to a normal subroutine is also being
01754 M01S01751.coding +++| used to void the instruction stack, the comment on the RJ should
01755 M01S01752.coding +++| note that fact.
01756 M01S01753.coding +++|
01757 M01S01754.coding +++| PP short jump instructions which must be modified are tested for
01758 M01S01755.coding +++| range errors. The LOC pseudo-op is used and the jump instruction is
01759 M01S01756.coding +++| actually assembled if the program size is not a critical factor.
01760 M01S01757.coding +++| For example:
01761 M01S01758.coding +++|
01762 M01S01759.coding +++| LDM TAGB
01763 M01S01760.coding +++| STM TAGA
01764 M01S01761.coding +++| .
01765 M01S01762.coding +++| TAGA MJN TAG1 IF TIME NOT EXPIRED
01766 M01S01763.coding +++| * UJN TAG2 (ONE CPU ONLY)
01767 M01S01764.coding +++| .
01768 M01S01765.coding +++| .
01769 M01S01766.coding +++| TAGB BSS O
01770 M01S01767.coding +++| LOC TAGA
01771 M01S01768.coding +++| UJN TAG2 comment
01772 M01S01769.coding +++| LOC *O
01773 M01S01770.coding +++|
01774 M01S01771.coding +++|1 PAGE 36
01775 M01S01772.coding +++|
01776 M01S01773.coding +++|
01777 M01S01774.coding +++| When program size is a constraining factor and the tag is to be
01778 M01S01775.coding +++| modified is previously defined, the ISTORE Macro defined in COMPMAC
01779 M01S01776.coding +++| should be used:
01780 M01S01777.coding +++|
01781 M01S01778.coding +++| ISTORE CADDR,(INSTR)
01782 M01S01779.coding +++|
01783 M01S01780.coding +++| where CADDR is the address of the code to be modified,
01784 M01S01781.coding +++| INSTR is the instruction (op code and address field) to be stored.
01785 M01S01782.coding +++|
01786 M01S01783.coding +++| For example:
01787 M01S01784.coding +++|
01788 M01S01785.coding +++| TAGA MJN TAG1 IF TIME NOT EXPIRED
01789 M01S01786.coding +++| * UJN TAG2 (ONE CPU ONLY)
01790 M01S01787.coding +++| .
01791 M01S01788.coding +++| .
01792 M01S01789.coding +++| .
01793 M01S01790.coding +++| ISTORE TAGA,(UJN TAG2)
01794 M01S01791.coding +++|
01795 M01S01792.coding +++| Which generates the following sequence of instructions:
01796 M01S01793.coding +++|
01797 M01S01794.coding +++| LDC **
01798 M01S01795.coding +++| ORG *-1
01799 M01S01796.coding +++| LOC TAGA
01800 M01S01797.coding +++| UJN TAG2
01801 M01S01798.coding +++| LOC *0
01802 M01S01799.coding +++| STM TAGA
01803 M01S01800.coding +++|
01804 M01S01801.coding +++| When program size is a constraining factor and the tag to be
01805 M01S01802.coding +++| modified has not yet been defined, the jump should be assembled as
01806 M01S01803.coding +++| part of an LDC instruction as follows:
01807 M01S01804.coding +++|
01808 M01S01805.coding +++| LDC UJNI+TAG2-TAGA
01809 M01S01806.coding +++| STM TAGA
01810 M01S01807.coding +++|
01811 M01S01808.coding +++| In this case, the ERRNG psuedo instruction must be used to test for
01812 M01S01809.coding +++| range errors as follows:
01813 M01S01810.coding +++|
01814 M01S01811.coding +++| ERRNG 37+daddr-jaddr (comment)
01815 M01S01812.coding +++| or
01816 M01S01813.coding +++| ERRNG 37+jaddr-daddr (comment)
01817 M01S01814.coding +++|
01818 M01S01815.coding +++| (depending on whether the jump is a backward or forward jump
01819 M01S01816.coding +++| respectively)
01820 M01S01817.coding +++|
01821 M01S01818.coding +++| Where:
01822 M01S01819.coding +++| jaddr =address of jump instruction
01823 M01S01820.coding +++| daddr =destination address of jump
01824 M01S01821.coding +++|
01825 M01S01822.coding +++| Again, instruction modification should be avoided in PP and CPU code
01826 M01S01823.coding +++| whenever possible.
01827 M01S01824.coding +++|
01828 M01S01825.coding +++|
01829 M01S01826.coding +++|1 PAGE 37
01830 M01S01827.coding +++|
01831 M01S01828.coding +++|
01832 M01S01829.coding +++| 3.3.11 COMMON DECK REGISTER USAGE
01833 M01S01830.coding +++|
01834 M01S01831.coding +++| CPU code within common decks avoids using registers A0, A5, X0 and
01835 M01S01832.coding +++| X5 unless absolutely necessary. If these registers must be used,
01836 M01S01833.coding +++| they should be restored before exiting to the calling routine.
01837 M01S01834.coding +++|
01838 M01S01835.coding +++|
01839 M01S01836.coding +++| 3.3.12 PP ADK, LDK, LMK, LPK, SBK Macros Usage
01840 M01S01837.coding +++|
01841 M01S01838.coding +++| Use of ADK, LDK, LMK, LPK, and SBK macros defined in COMPMAC are
01842 M01S01839.coding +++| encouraged, since the actual instruction assembled will be adjusted
01843 M01S01840.coding +++| to a 0, 1, or 2 byte instruction as needed, depending on the tag
01844 M01S01841.coding +++| values in the operand field. If the operand value reduces to zero,
01845 M01S01842.coding +++| no instruction will be generated (except for LDK). Operands to
01846 M01S01843.coding +++| these macros should not be numerics only (usefulness for tags is
01847 M01S01844.coding +++| recommended). Because of the variability of the code generated by
01848 M01S01845.coding +++| these instructions, this code should not be changed by in-line code
01849 M01S01846.coding +++| modifications.
01850 M01S01847.coding +++|
01851 M01S01848.coding +++|
01852 M01S01849.coding +++| 3.4 DATA USE, FORMAT, AND PARAMETERS
01853 M01S01850.coding +++|
01854 M01S01851.coding +++|
01855 M01S01852.coding +++| 3.4.1 LITERALS
01856 M01S01853.coding +++|
01857 M01S01854.coding +++| Literals may be used for read-only constants only. Error message
01858 M01S01855.coding +++| text should not be defined as literals, but rather should be defined
01859 M01S01856.coding +++| in data statements (preferably in tables).
01860 M01S01857.coding +++|
01861 M01S01858.coding +++|
01862 M01S01859.coding +++| 3.4.2 DATA FORMATS
01863 M01S01860.coding +++|
01864 M01S01861.coding +++| Data is specified in its natural form (readable and understandable
01865 M01S01862.coding +++| by humans) using post-radix symbols as required (see section
01866 M01S01863.coding +++| 3.6.1). If conversion considerations make this impossible, the
01867 M01S01864.coding +++| comment field will contain the natural form of the data. Octal
01868 M01S01865.coding +++| values are not used for character data unless the data cannot be
01869 M01S01866.coding +++| specified in any other way. When the VFD is used, it cannot
01870 M01S01867.coding +++| generate more than one CM word of data.
01871 M01S01868.coding +++|
01872 M01S01869.coding +++| If a data item does not require an initial value preset at assembly
01873 M01S01870.coding +++| time, BSS should be used to reserve space rather than CON.
01874 M01S01871.coding +++|
01875 M01S01872.coding +++| Only one piece of data is specified on a line of code unless a block
01876 M01S01873.coding +++| of data is being specified for use as a single data item to be
01877 M01S01874.coding +++| referenced by a single name.
01878 M01S01875.coding +++|
01879 M01S01876.coding +++|
01880 M01S01877.coding +++|1 PAGE 38
01881 M01S01878.coding +++|
01882 M01S01879.coding +++|
01883 M01S01880.coding +++| 3.4.3 TABLE GENERATION
01884 M01S01881.coding +++|
01885 M01S01882.coding +++| Tables which are generated with entry ordinals relative to the base
01886 M01S01883.coding +++| address of the table, should use the LOC pseudo-op as shown in the
01887 M01S01884.coding +++| following example:
01888 M01S01885.coding +++|
01889 M01S01886.coding +++| TFCN BSS 0 table entry
01890 M01S01887.coding +++| LOC 0
01891 M01S01888.coding +++| CON RNM first entry
01892 M01S01889.coding +++| CON ACF second entry
01893 M01S01890.coding +++| .
01894 M01S01891.coding +++| .
01895 M01S01892.coding +++| .
01896 M01S01893.coding +++| CON VSN last entry
01897 M01S01894.coding +++| LOC *O
01898 M01S01895.coding +++| TFCNL EQU *-TFCN table length (optional)
01899 M01S01896.coding +++|
01900 M01S01897.coding +++| Where tables are described, they are defined so they can be
01901 M01S01898.coding +++| processed by the "Documentation Table Generator". A description of
01902 M01S01899.coding +++| this format is found in the external documentation for the program
01903 M01S01900.coding +++| DOCMENT.
01904 M01S01901.coding +++|
01905 M01S01902.coding +++|
01906 M01S01903.coding +++| 3.4.4 DIRECT CELL USE
01907 M01S01904.coding +++|
01908 M01S01905.coding +++| Direct cells are defined using one of the following methods:
01909 M01S01906.coding +++|
01910 M01S01907.coding +++| 1. A single cell:
01911 M01S01908.coding +++|
01912 M01S01909.coding +++| xx EQU n description
01913 M01S01910.coding +++|
01914 M01S01911.coding +++| 2. Multiple cells:
01915 M01S01912.coding +++|
01916 M01S01913.coding +++| xx EQU n - m description
01917 M01S01914.coding +++|
01918 M01S01915.coding +++| 3. Contiguous cells:
01919 M01S01916.coding +++|
01920 M01S01917.coding +++| LOC n
01921 M01S01918.coding +++| xx BSS 1 description
01922 M01S01919.coding +++| yy BSS 5 description
01923 M01S01920.coding +++| .
01924 M01S01921.coding +++| .
01925 M01S01922.coding +++| .
01926 M01S01923.coding +++| zz BSS 1 description
01927 M01S01924.coding +++| LOC *0
01928 M01S01925.coding +++|
01929 M01S01926.coding +++|1 PAGE 39
01930 M01S01927.coding +++|
01931 M01S01928.coding +++|
01932 M01S01929.coding +++| 4. Contiguous direct cells or other sequential tag definitions
01933 M01S01930.coding +++| without reserving space:
01934 M01S01931.coding +++|
01935 M01S01932.coding +++| BEGIN BSSN n
01936 M01S01933.coding +++| xx BSSN 1 description
01937 M01S01934.coding +++| yy BSSN 5 description
01938 M01S01935.coding +++| .
01939 M01S01936.coding +++| .
01940 M01S01937.coding +++| .
01941 M01S01938.coding +++| zz BSSN 2 description
01942 M01S01939.coding +++| END BSSN
01943 M01S01940.coding +++|
01944 M01S01941.coding +++| The BSSN macro is defined in COMCMAC and COMPMAC.
01945 M01S01942.coding +++|
01946 M01S01943.coding +++| Where:
01947 M01S01944.coding +++|
01948 M01S01945.coding +++| xx, yy, zz = the tag for the cell
01949 M01S01946.coding +++| n = location of the cell (or first cell)
01950 M01S01947.coding +++| m = location of the last cell
01951 M01S01948.coding +++|
01952 M01S01949.coding +++| Multiple definitions of direct cells should be avoided.
01953 M01S01950.coding +++|
01954 M01S01951.coding +++| The first few direct cells in the PP should not be used for data
01955 M01S01952.coding +++| which is critical to debugging. The deadstart dump process
01956 M01S01953.coding +++| destroys the contents of these locations:
01957 M01S01954.coding +++|
01958 M01S01955.coding +++| T0 - T3 and 7774 - 7777
01959 M01S01956.coding +++|
01960 M01S01957.coding +++|
01961 M01S01958.coding +++| 3.4.5 BUFFER DEFINITIONS
01962 M01S01959.coding +++|
01963 M01S01960.coding +++| Large buffers and working storage areas should be defined using EQU
01964 M01S01961.coding +++| statements (rather than BSS and BSSZ) to avoid unneccessary loading
01965 M01S01962.coding +++| of the buffer areas that do not require initialization. This
01966 M01S01963.coding +++| applies to CPU and PP code.