KM10.S2MEMO 24 MAY 77 !!! !! STAGE2 THIS SHORT MEMO DESCRIBES THE USE AND IMPLEMENTATION OF THE STAGE2 MACRO-GENERATOR UNDER VM/370. INPUT/OUTPUT IS HANDLED BY CALLING BCPL LIBRARY ROUTINES, AND THE SYSTEM SHOULD THEREFORE RUN UNDER OS WITHOUT NEED FOR MODIFICATION. REFERENCE WILLIAM M. WAITE 'IMPLEMENTING SOFTWARE FOR NON-NUMERIC APPLICATIONS', PRENTICE-HALL 1973. THE LANGUAGE IMPLEMENTED IS THAT DEFINED IN THE BOOK WITH A SINGLE EXCEPTION ; THE MACRO SOURCE HAS BEEN MODIFIED SO THAT END-OF-FILE DURING THE GENERATION PHASE WILL CAUSE AN ERROR MESSAGE ONLY IF THE SKIP COUNT IS NON-ZERO. INPUT/OUTPUT STAGE2 INPUT/OUTPUT IS DEFINED WITH RESPECT TO UNITS NUMBERED 0 TO 9. UNIT 0 HAS ATTRIBUTES OF DUMMY, I.E. IMMEDIATE END-OF-FILE ON INPUT, WITH ANY LINES OUTPUT BEING LOST. THE BASIC OPERATIONS FOR THE OTHER UNITS ARE TO READ OR WRITE A LINE, AND POSSIBLY TO REWIND. THE STAGE2 PROCESSOR READS MACRO-DEFINITIONS AND TEXT INITIALLY FROM UNIT 1, WRITES MACHINE-READABLE (CORRECTLY GENERATED) OUTPUT TO UNIT 3, AND DIRECTS ANY ERROR MESSAGES TO UNIT 4. UNIT 2 IS BY CONVENTION AVAILABLE AS A UTILITY FILE. IN THE CURRENT IMPLEMENTATION THERE ARE SIX POSSIBLE STATES FOR EACH UNIT AT ANY STAGE OF THE GENERATION PROCESS. 1. UNSET NO SPECIFIC ATTRIBUTE AT PRESENT. 2. DUMMY UNIT HAS DUMMY ATTRIBUTES. 3. READING CURRENTLY AN INPUT DEVICE. 4. WRITING CURRENTLY AN OUTPUT DEVICE. 5. READING RESERVED AS AN INPUT DEVICE. 6. WRITING RESERVED AS AN OUTPUT DEVICE. UNITS IN STATES 3 AND 4 CAN BE REWOUND AT ANY STAGE OF GENERATION, THE STATUS THEN BEING UNSET. ANY ATTEMPT TO READ/WRITE FROM AN UNSET UNIT WILL CAUSE THE UNIT TO BE OPENED FOR INPUT/OUTPUT, THE STATUS BEING SET TO READING/WRITING RESPECTIVELY. STATES 5 AND 6 ABOVE DEFINE UNITS TO BE 'RESERVED' ; FOR RESERVED UNITS REWIND IS AN INVALID OPERATION. THIS OPTION IS PROVIDED TO GUARANTEE THE INTEGRITY OF INPUT FILES AND TO PRESERVE THE OUTPUT STATUS OF SOME UNITS, IN PARTICULAR THE ERROR MESSAGE UNIT. THE BCPL SYSTEM UNDER VM PERFORMS INPUT/OUTPUT BY MEANS OF THE CMS SIMULATION OF OS ACCESS METHODS, AND IT IS THEREFORE NECESSARY TO TIE THE STAGE2 UNITS TO SPECIFIC FILES BY MEANS OF THE FILEDEF COMMAND. EACH UNIT IN THE RANGE 1 TO 9 MAY BE CONNECTED TO ONE OR MORE DD-NAMES ; IF A UNIT IS OPEN FOR INPUT DATA WILL BE READ FROM THE VARIOUS DD-NAMES GIVEN UNTIL END-OF-FILE IS REACHED ON THE LAST FILE. THE FOLLOWING ARE THE DEFAULT ASSOCIATIONS FOR THE VARIOUS STAGE2 UNITS. UNIT DDNAME STATUS 0 - DUMMY 1 SYSIN READING, RESERVED 2 UNIT2 UNSET 3 OUTPUT UNSET 4 SYSPRINT WRITING, RESERVED 5 - 9 - DUMMY STAGE2 COMMAND LINE STAGE2 IS AN EXECUTABLE MODULE THAT HAS BEEN PRODUCED BY THE GENMOD COMMAND. IF INVOKED WITH A NULL PARAMETER LIST THE ENVIRONMENT IS THAT DEFINED BY THE DEFAULT UNIT ASSOCIATIONS. THESE MAY HOWEVER BE VARIED BY GIVING NEW DEFINITIONS IN THE COMMAND LINE ; THE SYNTAX FOR THE PARAMETER LIST IS GIVEN BELOW, ASSUMING THAT FOLLOWS OS JCL CONVENTIONS, AND THAT IS A SINGLE DIGIT IN THE RANGE 1 TO 9. SPACES ARE ONLY SIGNIFICANT IN THAT THEY DELIMIT DD-NAMES. WHEN SCANNING A DD-LIST A NEW DD-NAME WILL BE ACCEPTED AUTOMATICALLY AFTER 8 NON-BLANK CHARACTERS, WHETHER OR NOT THERE IS A DELIMITING SPACE OR COMMA (THIS SPECIAL CASE IS INTENDED TO MAKE LIFE EASY UNDER VM TOKENISATION). ::= (I) (O) ::= , ::= ::= (D) ::= ::= ; ::= HOPEFULLY THIS INFORMAL DEFINITION CONVEYS THE MEANING INTENDED ; HERE FOLLOW TWO EXAMPLES OF VALID STRINGS. 1 (I) MACRO TEXT 4 (D) 5 UTILITY 3 (O) OUTPUT; 5 (I) TEXT,MORETEXT THE FIRST EXAMPLE (VM-LIKE) DECLARES THAT PRIMARY INPUT IS TO BE TAKEN FIRST FROM THE FILE DEFINED BY DD-NAME MACRO, THEN FROM THE FILE DEFINED BY DD-NAME TEXT ; AND THAT THE DD-NAME UTILITY IS ATTACHED TO UNIT 5 (WITHOUT THIS THE UNIT SPECIFICATION OF DUMMY WOULD BE ASSUMED). FURTHER, ANY ERROR MESSAGES GENERATED ARE TO BE THROWN AWAY (NOT A GOOD IDEA!). THE SECOND EXAMPLE (OS-LIKE) RESERVES THE MACHINE-READABLE OUTPUT UNIT, AND DEFINES A CONCATENATION OF FILES AS INPUT TO UNIT 5. THERE ARE THREE SEMANTIC RESTRICTIONS ON THE PARAMETER LIST ; IF ANY OF THESE IS BROKEN THE RUN IS TERMINATED WITH A COMPLETION CODE OF 12. 1. A UNIT SPECIFICATION MAY BE GIVEN ONCE ONLY FOR EACH UNIT. 2. UNIT 1 MAY NOT BE RESERVED FOR OUTPUT (FOR OBVIOUS REASONS). 3. UNIT 4 MAY NOT BE RESERVED FOR INPUT (ERROR SITUATIONS HURT). COMPLETION CODES IF TERMINATION IS NORMAL (PROCESSOR CALL %F0 IS ISSUED, OR THERE IS AN END-OF-FILE WHEN READING TEXT FOR EXPANSION) THE COMPLETION CODE IS 0. NON-ZERO CODES ARE RETURNED BY STAGE2 IN THREE ERROR SITUATIONS. CODE 4 INSUFFICIENT STORAGE TO CONTINUE CODE 8 I/O ERROR (OR END-OF-FILE DURING THE DEFINITION PHASE) CODE 12 INVALID PARAMETER LIST SYNTAX OR SEMANTICS SINCE STAGE2 RUNS UNDER THE BCPL RUN-TIME SYSTEM BCPL RUN-TIME ERROR CODES MAY ALSO BE RETURNED. THE CODES THAT ARE LIKELY ARE THE FOLLOWING. CODE 60 INSUFFICIENT STORAGE TO INITIALISE BCPL CODE 80 SAME AS CODE 60, BUT A CLOSER THING ! CODE 88 INVALID RUN-TIME OPTION STRING CODE 100 FATAL ERROR DURING STAGE2 EXECUTION THE FIRST THREE SITUATIONS ABOVE HAVE OBVIOUS REMEDIES. COMPLETION OF 100 ARISES ONLY IF THE STAE OR SPIE EXIT IS TAKEN, AND IT WOULD INDICATE THAT SOMETHING RATHER NASTY WAS GOING ON ; PROBABLY A BUG EITHER IN THE STAGE2 SOURCE, OR MUCH MORE LIKELY IN THE MACRO-IMPLEMENTATION OF THE FLUB MACHINE. IMPLEMENTATION THE 370 SYSTEM WAS BROUGHT UP BY THE 'FULL-BOOTSTRAP' TECHNIQUE THAT IS DESCRIBED IN WAITE'S BOOK, BUT WITHOUT THE USE OF ANY OF THE FORTRAN AIDS. A BCPL PROGRAM WAS WRITTEN TO IMPLEMENT SIMCMP, AND THE MACRO-SOURCE WAS EXPANDED DIRECTLY TO ASSEMBLER LANGUAGE. THE INPUT/OUTPUT MACROS WERE HANDLED BY CALLING BCPL-WRITTEN SUBROUTINES TO INITIATE THE TRANSFERS, THE ASSEMBLER ROUTINE SATISFYING BCPL CONVENTIONS AND RUNNING UNDER THE BCPL RUN-TIME SYSTEM. SPACE FOR THE FLUB REGISTERS IS ALLOCATED IN THE BCPL GLOBAL VECTOR ; THE FLUB MACHINE STORE IS OBTAINED BY ENTERING THE STAGE2 PROGRAM VIA AN APTOVEC FROM THE STEERING PROGRAM. ONCE THE INITIAL VERSION HAD BEEN THOROUGHLY TESTED AN OPTIMISED SYSTEM WAS OBTAINED BY USING MORE SOPHISTICATED MACRO-DEFINITIONS. AT THE SAME TIME A TRANSPORTABLE SYSTEM WAS CONSTRUCTED BY MACRO-EXPANSION TO BCPL ; ALL THREE VERSIONS RUN UNDER THE SAME STEERING PROGRAM, THE RELATIVE LENGTHS BEING APPROXIMATELY 10 : 9 : 16 . FOR DETAILS OF THE RUN-TIME ENVIRONMENT AND A DESCRIPTION OF THE BCPL SYSTEM UNDER VM SEE THE FILE BCPL MEMO . ?? ??? END KM10.S2MEMO 24 MAY 77 ??? ?? !! !!!