F O C A L - 1 1 (R S X VERSION) EXTENDED INSTRUMENTATION VERSION 011A ABSTRACT: RSX INSTRUMENTATION FOCAL IS A VERSION OF FOCAL-11 THAT RUNS UNDER RSX AND HAS EXTENSIONS FOR DEVICE CONTROL. FOCAL IS A TRUE MULTI-USER TASK; THE BULK OF THE INTERPRETER IS PURE, SHARED CODE, WHILE USER TEXT AND VARIABLES ARE UNIQUE TO EACH USER. IN ADDITION, A SINGLE USER VERSION MAY BE ASSEMBLED WHICH CAN HANDLE UP TO 15 INTERRUPTS. THIS FACILITY REQUIRES AN EXTERNAL PAGE COMMON AND SUPERVISOR SPACE, AND WORKS THOUGH FOCAL IS NOT A PRIVILEGED TASK. EXTENSIVE SUPPORT OF RSX I/O IS PROVIDED. FOCAL CAN EXECUTE QIO$ INSTRUCTIONS TO ANY DEVICE, EXECUTE ANY RSX EMT CALL, OR DO FILE-STRUCTURED READING AND WRITING IN SEQUENTIAL OR RANDOM MODES, PERMITTING VIRTUAL ARRAYS IF THE USER SO DESIRES. THESE FACILITIES MAY BE EXCLUDED BY CONDITIONAL ASSEMBLY IF NEED BE. HOWEVER, MANY LANGUAGE EXTENSIONS ARE PROVIDED TO MAKE FOCAL USEFUL IN CALCULATIONS. THESE INCLUDE THE ABILITY TO DO BOOLEAN OPERATIONS, FULL SUPPORT OF THE OCTAL RADIX, ABILITY TO EDIT LINE NUMBERS AS WELL AS TEXT, AND A "JUMPON" COMMAND SIMILAR TO 'IF' EXCEPT THAT CONTROL IS TRANSFERRED BY A 'DO' RATHER THAN BY A 'GOTO'. THIS MAKES IT EASIER TO WRITE STRUCTURED CODE IN FOCAL IF DESIRED. ALL NORMAL TRIG FUNCTIONS (INCLUDING ARCTAN) AND LOG/EXP ARE AVAILABLE, AS WELL AS LIBRARY SUPPORT FOR READING OR WRITING PROGRAM CODE TO ANY RSX DATASET. WRITEUP: RSX FOCAL IS A TRANSLATION OF DOS INSTRUMENTATION FOCAL, A VERSION OF THE LANGUAGE WITH MANY EXTENSIONS FOR VERSATILE INSTRUMENT CONTROL. WHILE NOT A PRIVILEGED TASK, FOCAL MAY, WHERE BUILT WITH A COMMON IN THE EXTERNAL PAGE (WHICH IS BUILT WITH DEFAULT PARTITION $$$EXT AND NO HEADER), OBTAIN THE BUS ADDRESS OF ANY OF ITS DATA ELEMENTS AND HANDLE UP TO 15 QUASI- ASYNCHRONOUS INTERRUPTS. ALL DIRECTIVES USED BY RSX FOCAL ARE BELIEVED TO BE AVAILABLE IN RSX11M V3 OR LATER, AND ARE KNOWN TO BE PRESENT IN RSX11D V6 OR LATER (AND BY IMPLICATION IN IAS). THUS, RSX FOCAL V11A SHOULD RUN WITHOUT CHANGE UNDER ANY RSX/IAS SYSTEM. RSX FOCAL USES THE GCML$ FACILITY TO HANDLE ITS CONSOLE INPUT, WITH UP TO 2 LEVELS OF INDIRECTION PERMITTED (EASILY EXPANDED IF NEED BE.) A CONDITIONALLY ASSEMBLED SECTION OF FOCAL (DEFINE THE PARAMETER "GBEVF" WHEN ASSEMBLING FCLMAI.MAC) WILL CAUSE FOCAL TO RESTART WHENEVER THE GLOBAL EVENT FLAG #56. IS SET, AND WILL CLEAR THAT EVENT FLAG AT THAT TIME. THIS FACILITY IS INTENDED TO PROVIDE A MEANS TO RECOVER CONTROL WHEN A FOCAL PROGRAM ENTERS A LOOP. IT WILL NOT DISTINGUISH BETWEEN MULTIPLE VERSIONS OF FOCAL RUNNING, BUT IT WILL USUALLY BE SEEN FIRST BY A COPY OF FOCAL THAT IS IN A LOOP OUT OF CONTROL. IF FOCAL IS RESTARTED IN THIS WAY, PROGRAM AND VARIABLES MAY BE RECOVERED. ANOTHER MCR TASK (EASIEST TO WRITE IN FORTRAN) TO SET EVENT FLAG 56 IS NEEDED TO ALLOW THIS FEATURE TO WORK MOST CONVENIENTLY. HOWEVER, BECAUSE OF ITS SHOTGUN TYPE NATURE, THIS APPROACH SHOULD BE USED ONLY WHERE IT IS REALLY NEEDED. A SINGLE LEVEL OF LIBRARY READ IS PERMITTED TO ALLOW PROGRAM CHAINING. EITHER GCML$ I/O IS INPUTTING OR LIBRARY INPUT IS ACTIVE--ONE AT A TIME.(TO A DEGREE, INPUT MAY BE USER OR PROGRAM SELECTED WITH BOTH OPEN AT ONCE.) HOWEVER, LIBRARY OUTPUT IS AS IN DOS, WITH SEPARATE OPEN AND WRITE COMMANDS TO SAVE VARIABLES OR PROGRAMS. THE OPERATE COMMAND IS SUPPORTED FOR NON-FILE DEVICES, THOUGH DEFAULT FILENAME BLOCKS CONTROL THIS, AND DEFAULT FILES CAN BE WRITTEN BY *OPERATE* IF DESIRED. NOTE THAT THE LIBRARY READ COMMAND WILL NOT ACTUALLY BEGIN READING THE LIBRARY FILE. TO READ THE LIBRARY, USE THE "OPERATE A" STATEMENT, AND TO READ THE CONSOLE USE THE "OPERATE K" STATEMENT. THESE WILL SET UP MODES OF LIBRARY VS. NON-LIBRARY READS. FOR THE COMPLETE FOCAL WITH ALL BELLS AND WHISTLES, LUN USAGE IS AS FOLLOWS: LUN USE 1 GCML$ INPUT 2 CONSOLE OUTPUT (TI:) 3 LIBRARY OUTPUT 4 LIBRARY DELETIONS 5 OPERATE P (SY:FOCALDAT.DAT DEFAULT) 6 LUN FOR LIBRARY READ DATASET 7 OPERATE L (LP: DEFAULT) 8 OPERATE V (VT: --VT01-- DEFAULT) 9 OPERATE W (VT:FOCALSCP.FCL DEFAULT) 10 OPERATE X (TI:FOCALSCP.FCL DEFAULT) 11 OPERATE Y (GB:GARBAGE.FCL DEFAULT) 12 OPERATE Z (GB:GARBAGE.FCL DEFAULT) 13 OPERATE G (GB: --GARBAGE DEVICE OR 'BLACK HOLE'-- DEFAULT) 14 'USING Q ...' DATASET 15 'USING R ...' DATASET 16 'USING S ...' DATASET 17 'USING T ...' DATASET 18 'USING 1 ...' DATASET 19 'USING 2 ...' DATASET 20 'USING 3 ...' DATASET 21 'USING 4 ...' DATASET 22 FRCHR INPUT DATASET 23 FRCHR OUTPUT DATASET 1. OCTAL NUMBERS AN OCTAL NUMBER MAY BE REPRESENTED ANYWHERE BY PREFIXING IT WITH AN "@" SIGN. ON INPUT, THIS CAUSES THE NUMBER TO BE READ AS AN INTEGER; ON OUTPUT, NUMBERS WILL BE PRINTED AS 16-BIT OCTAL INTEGERS. ON INPUT, UP TO 24 BIT OCTAL NUMBERS MAY BE ENTERED. THUS, TO INPUT A NUMBER OR REPRESENT AN OCTAL NUMBER ANYWHERE IN A PROGRAM, TYPE IT WITH AN @ IN FRONT. TO OUTPUT AN OCTAL NUMBER, PUT AN @ IN FRONT OF THE NUMBER OR VARIABLE TO BE PRINTED. NUMBERS PRINTED IN OCTAL WILL HAVE 6 DIGITS TYPED, EVEN IF THE FIRST SEVERAL OF THEM ARE ZERO. EXAMPLES: S B=40;T @B,! ;TYPE B IN OCTAL 000050 ;VALUE OF B IS 50 OCTAL (=40 DECIMAL) S C=@100;T C,! 64 ;100 OCTAL IS 64 DECIMAL ASK A;T A,! @200 128.000 ;200 OCTAL IS 128 DECIMAL OCTAL NUMBERS MAY BE AS LARGE AS DESIRED, SINCE THEY ARE ENTERED BY MULTIPLYING SUCCESSIVE DIGITS BY 8. INSTEAD OF 10. AS FOR DECIMAL. THIS WILL PRODUCE STRANGE RESULTS WHERE E FORMAT NUMBERS ARE ENTERED, BUT FOR NUMBERS WITHIN THE CORRECT 16-BIT RANGE WILL PRODUCE NO SURPRISES. ON OUTPUT, OCTAL NUMBERS ARE TREATED AS UNSIGNED 16-BIT NUMBERS AND SO DISPLAYED. BECAUSE THE CHARACTER "@" SERVES AS A FORMAT INDICATOR FOR OUTPUT AND ALSO A RADIX INDICATOR FOR NUMBERS, ONE MAY TYPE AN OCTAL NUMBER IN OCTAL BY AN EXPRESSION OF FORM: TYPE @@77 000077 WHERE THE DOUBLE "@" CAUSES THE NUMBER TO BE TYPED IN OCTAL AND EVALUATED IN OCTAL. (THE USES OF THIS ARE SOMEWHAT HARD TO SEE.) 2. BOOLEAN FUNCTIONS THE NEW FUNCTIONS FAND AND FIOR GIVE THE BOOLEAN "AND" OR THE BOOLEAN "INCLUSIVE OR" OF TWO ARGUMENTS, TAKEN AS INTEGERS. THESE ARE USEFUL FOR TESTING BITS OF DEVICE STATUS REGISTERS READ IN BY FX. 3. FX--UNIBUS ACCESS FX HAS BEEN EXPANDED SO THAT A CALL OF THE FORM FX(-2,BUSS.ADDR,DATA) PUTS THE WORD DATA INTO THE ADDRESS GIVEN AS "BUSS.ADDR" MOVING IT AS A WORD. FX(2,BUSS.ADDR) READS THE WORD AT THE ADDRESS "BUSS.ADDR" AS A 16-BIT INTEGER. BOTH OF THESE FUNCTIONS WILL FORCE AN EVEN ADDRESS, AND HAVE NO RESTRICTIONS ON THE UNIBUS ADDRESSES THEY SELECT. NOTE THAT IF "BUSS.ADDR" IS EXPRESSED AS A NUMBER, THE NUMBER WILL DEFAULT TO OCTAL, NOT DECIMAL. THIS IS THE ONLY PLACE IN FOCAL WHERE AN OCTAL NUMBER IS NOT PRECEDED BY AN @ SIGN. WHERE BYTE OPERATIONS ARE NEEDED, FX(-1,BUS ADDR,DATA) WILL MOVE A BYTE TO BUSS ADDR, FX(1,BUS ADDR) WILL READ BUS ADDR, AND FX(0,BUS ADDR,DATA) WILL 'AND' DATA AND THE WORD AT "BUS ADDR" TOGETHER. YOU MAY WRITE ANY READ/WRITE ADDRESS IN THE FOCAL ADDRESS SPACE EXCEPT ADDRESSES BELOW OCTAL 60 (TO PROTECT THE DSW AND A FEW RSX NEEDED WORDS). NOTE FOR MAPPED SYSTEMS THAT THE ADDRESSES GIVEN ARE IN USER VIRTUAL SPACE, WITH ALL THE PECULIARITIES THAT IMPLIES. THUS, EXTERNAL PAGE DEVICES ARE NORMALLY NOT MAPPED INTO APR7, AS AN EXAMPLE. TO FIND THE REAL BUS ADDRESS OF ANY USER VIRTUAL ADDRESS, FBUS[ADDRESS] RETURNS THE LOW 16 BITS OF THE BUS ADDRESS AND FBUSH[ADDRESS] RETURNS THE HIGH BITS (2 ON 11/40 AND 11/45; 6 ON 11/70) SHIFTED LEFT 4 PLACES. (THIS IS TO MAP THEM INTO BITS 4 AND 5, THE STANDARD POSITION FOR EXTENDED ADDRESS BITS IN UNIBUS DEVICE REGISTERS.) IT IS UP TO THE USER TO KEEP ADDRESSES STRAIGHT. FOCAL CANNOT SAFELY ALLOCATE UMR'S ON AN 11/70, HOWEVER, SO THAT ITS USE OF NPR UNIBUS DEVICES VIA INTERRUPTS MUST BE RESTRICTED IN THAT ENVIRONMENT. (FOR THOSE NOT FAMILIAR WITH THE 11/70 CPU, A UMR IS A UNIBUS MAPPING REGISTER THAT MAPS THE UNIBUS 124K ADDRESS SPACE INTO REAL MEMORY.) 3. INTERRUPT HANDLING YOU CAN GET FOCAL TO SERVICE AN INTERRUPT BY EXECUTING A GROUP OR LINE OF YOUR CHOICE WHEN AN INTERRUPT OCCURS. THIS IS DONE USING THE FUNCTION "FINT", WHOSE ARGUMENTS ARE FINT(PRIORITY,INT.VECTOR.ADDR, GROUP.LINE,DEV.CSR.ADDR, WORD) WHERE PRIORITY IS THE RELATIVE PRIORITY (1 TO 15) OF THE INTERRUPT INT.VECTOR ADDR IS THE ADDRESS OF THE DEVICE INTERRUPT VECTOR GROUP.LINE IS THE GROUP.LINE NUMBER OF THE FOCAL CODE THAT SHOULD GAIN CONTROL WHEN AN INTERRUPT OCCURS DEV.CSR ADDR IS THE DEVICE CONTROL/STATUS REGISTER ADDRESS WORD IS A WORD TO BE PUT INTO THE CSR AT THE MOMENT OF AN INTERRUPT. THE INTERRUPT IS SERVICED AS SOON AS FOCAL SEES AN END OF ANY COMMAND AND IS INVISIBLE TO THE RUNNING PROGRAM. THE WORD PUT INTO THE CSR IS USUALLY USED TO TURN OFF FURTHER INTERRUPTS UNTIL ONE CAN BE SERVICED. FX IS USED TO ENABLE THE INTERRUPT IN THE FIRST PLACE, AND IF DESIRED IT CAN DISABLE THE INTERRUPT, EFFECTIVELY CANCELING THE REQUEST IF NO INTERRUPT HAS YET OCCURRED. FX IS ALSO USED TO HANDLE THE DEVICE INSIDE THE INTERRUPT SERVICE SECTION OF YOUR FOCAL PROGRAM TOO. THIS CAPABILITY PERMITS FOCAL TO BE USED FOR SOME FORMS OF DATA COLLECTION OR DEVICE TESTS THAT REQUIRE RESPONSE TO EXTERNAL SIGNALS ASYNCHRONOUSLY. THE 15 INTERRUPTS ARE LABELLED EACH BY ITS SOFTWARE PRIORITY. THUS, EACH INTERRUPT ENABLED MUST HAVE ITS OWN PRIORITY AND NO TWO PRIORITIES SHOULD BE THE SAME. INTERRUPTS ARE ONLY QUASI-ASYNCHRONOUS IN RSX FOCAL (AS IN FOCAL/RT). THE INTERPRETER CHECKS AFTER EACH COMMAND TO SEE IF ANY INTERRUPT AT A HIGHER PRIORITY THAN THE CURRENT ONE WANTS TO BE SERVICED, AND IF SO STARTS IT UP. OTHERWISE, THE PROCESSOR CONTINUES NORMALLY. THIS IMPLIES THAT FOCAL MUST BE RUNNING A PROGRAM FOR INTERRUPTS TO BE SERVICED. THUS, A LOOP INSTEAD OF A QUIT AFTER A SECTION OF CODE TO BE DONE IN THE BACKGROUND IS DESIRABLE. ALSO, SOME LONG COMMANDS WILL EFFECTIVELY PREVENT INTERRUPTS. FOR INSTANCE, IF AN "ASK" COMMAND IS AWAITING CONSOLE INPUT, IT WILL NOT TERMINATE UNTIL THE REPLY IS TYPED IN, AND INTERRUPTS WILL NOT BE SERVICED UNTIL THAT HAPPENS. THE USING N,LOOP COMMAND ALSO MAY BE LONG, DEPENDING ON THE DEVICE. SINCE NORMAL FOCAL CONSOLE ACTIVITY TIES UP THE INTERPRETER, FRCHR IS PROVIDED TO ALLOW SOME CONSOLE INTERACTION WITHOUT WAITING. FRCHR MAY BE SAMPLED TO DETERMINE IF CONSOLE I/O IS POSSIBLE, AND USED TO KEEP ANY "ASK" COMMANDS FROM BEING EXECUTED UNTIL A FLAG CHARACTER IS ISSUED FROM THE CONSOLE. THIS WILL MINIMIZE DEAD TIME. OUTPUT MAY BE CARRIED OUT IN LIKE FASHION. A ZERO INPUT TO FRCHR IS ILLEGAL AND WILL BE FLAGGED AS AN ERROR. FOR RSX11D, FOCAL IS TOO LARGE TO BE A REAL PRIVILEGED TASK, AND THIS COMPLICATES THE INTERRUPT PROCEDURE. HENCE THE FOLLOWING SCHEME IS USED. 1. AN EXTERNAL PAGE COMMON MUST BE AVAILABLE TO PERMIT FOCAL TO MANIPULATE THE APR'S. 2. SINCE RSX ONLY KNOWS ABOUT KERNEL AND USER SPACES, AND SINCE THE INTERRUPT MUST ALWAYS BE MAPPED IN, FOCAL WILL SET UP SUPERVISOR APR'S (OR GIVE ERROR 09 ON AN 11/40; SORRY 'BOUT THAT) TO POINT APR7 TO THE EXTERNAL PAGE AND APR6 TO THE FOCAL INTERRUPT SERVICE ROUTINE, WHICH WILL THEN BE ABLE TO ACCESS DEVICES AT THEIR STANDARD ADDRESSES. 3. FOCAL WILL THEN USE MTPI TO BASH THE SUPERVISOR STACK TO AN INTERNAL STACK AND TO SET UP THE INTERRUPTS IN KERNEL VIRTUAL SPACE. IT WILL *NOT* CHECK THE VECTORS IN ANY WAY (EXCEPT THAT THE EMT VECTOR WILL BE PROTECTED) BUT WILL SET INTERRUPT SERVICES UP TO RUN IN SUPERVISOR MODE. 4. THE FOCAL INTERRUPT SERVICE ROUTINE WILL EXECUTE AT PRIORITY 7 AND SET SOME FLAGS UP, THEN EXIT VIA RTI. HOPEFULLY, RSX WILL NEVER FIND OUT WHAT'S GOING ON. IF A USER LEAVES ANY INTERRUPTS ENABLED WHEN HE EXITS FOCAL, OR IF 2 USERS TRY TO RUN THIS FACILITY AT A TIME, THE SYSTEM WILL PROBABLY CRASH. THE SUPERVISOR APR'S WILL NOT ACTUALLY BE TOUCHED UNTIL A FINT IS CALLED, THOUGH. IN FACT, UNLESS FOCAL IS ABORTED, IT WILL ATTEMPT TO DISABLE ALL INTERRUPTS ON EXIT BY PUTTING THE MASKS GIVEN INTO THE CSR'S OF DEVICES DEFINED. THIS SHOULD LARGELY PROTECT THE SYSTEM, BUT BE AWARE THAT IF INVALID ADDRESSES FOR CSR'S ARE GIVEN AND ANY INTERRUPTS ARE SET UP, THE SYSTEM WILL CRASH. CARE MUST BE TAKEN!! IF A REPEATED FAILURE TO CLEAR THESE ADDRESSES OCCURS, AT MOST 15 ATTEMPTS TO EXIT (= NUMBER OF INTERRUPTS) WILL BE NEEDED. NO ACTION IS TAKEN TO CANCEL OUTSTANDING ALARMS. FOCAL WILL TRY TO CLOSE LIBRARY FILES AND OPERATE OUTPUT FILES AND CLEAN UP INTERRUPTS ON EXIT FOR ANY REASON, BUT MAY BE ABORTED AND LEAVE FILES OPEN. ALSO, "USING" FILES ARE NOT CLEANED UP ON EXIT; THAT IS THE USER'S RESPONSIBILITY IF THE "USING" STATEMENT HAS BEEN CONDITIONALLY ASSEMBLED IN (I.E., "XUSING" NOT DEFINED AT ASSEMBLY TIME.) SYSTEM VARIABLES A SPECIAL CLASS OF VARIABLES IS MAINTAINED WHICH ARE NEVER ERASED OR DE-ALLOCATED. THESE ARE THE VARIABLES &A THROUGH &Z INCLUSIVE, AND &&. THESE ARE NORMAL FOCAL FLOATING-POINT SCALARS, AND ARE USEFUL FOR PASSING DATA BETWEEN CHAINED PROGRAMS OR FOR INTERRUPT PROCESSES THAT NEED A GUARANTEED DATA BASE. IF IT IS DESIRED TO HAVE VARIABLES THAT ARE LEFT IN BEING ACROSS CALLS TO FOCAL (OR FOR COMMUNICATION BETWEEN DIFFERENT VERSIONS OF FOCAL IN CORE), VARIABLES MAY BE ASSEMBLED INTO A GLOBAL COMMON AREA WITH THE LOWEST ADDRESS OF THE AREA LABELLED (GLOBALLY) GBCDB, AND THE HIGHEST ADDRESS LABELLED GBCDE. THE DATA MAY CONTAIN ANY MIXTURE OF VECTORS AND FOCAL SCALARS WITH LABELS AND SUBSCRIPTS PRESET, AND MUST BE READ/WRITE ACCESSED TO BE USED. TO INCLUDE THIS FEATURE IN FOCAL, ASSEMBLE WITH "GBCMN" DEFINED. FOCAL WILL NOT INCLUDE THIS FEATURE BY DEFAULT. RECALL THAT VAIRABLES LOOK LIKE THIS: .BYTE 'N ;FIRST LETTER OF NAME (+200 IF SCALAR WITHOUT SUBSCRIPT) .BYTE 'M ;2ND LETTER OF NAME (+200 IF DBL SUBSCRIPT) .WORD 23 ;SUBSCRIPT (23 OCTAL IN THE EXAMPLE, FOR NM(19) .WORD 0,0 ;DATA AREA, 2 WORDS AND VECTORS LOOK LIKE THIS: .ASCII /V%/ ;VECTOR NAME .WORD 0 ;SUBSCRIPT .WORD LENGTH ;MAXIMUM SUBSCRIPT .BLKW LENGTH+1;DATA AREA FOR USER CONVENIENCE, THE VARIABLE "&@" IS PREDEFINED TO CONTAIN THE VALUE OF PI (3.14159...) AND THE VARIABLE "&:" CONTAINS 180/PI (ABOUT 57) FOR CONVERSION OF ANGLES FROM RADIANS TO DEGREES. THE VARIABLES &8 AND &9 CONTAIN CONVERSION FACTORS FOR TRIG FUNCTIONS AND ARE INITIALLY 1.0. &8 IS THE CONVERSION FOR INPUT ANGLES TO FSIN AND FCOS FROM ANY UNITS INTO RADIANS; &9 IS THE OUTPUT CONVERSION FACTOR FROM FATN FROM RADIANS INTO ANY UNITS. INPUTS AND OUTPUTS ARE MULTIPLIED BY THESE NUMBERS TO ALLOW THE TRIG FUNCTIONS TO EXPRESS ANGLES IN ANY DESIRED UNITS. THE COMMANDS: SET &8=1./&: SET &9=&: WILL CAUSE THE TRIG FUNCTIONS TO ACCEPT AND PRODUCE ANGLES IN DEGREES, FOR INSTANCE. DOING NOTHING WILL ALLOW THEM TO USE AND PRODUCE ANGLES IN RADIANS. THERE IS ALSO A SYSTEM VECTOR VARIABLE NAMED &%, WITH LENGTH OF 5. VECTOR ELEMENT &%(1) IS THE CHARACTER USED FOR *ASK* INPUT. NORMALLY THIS WILL BE SET TO 60 OCTAL (ASCII ZERO) TO FORCE NUMERIC EVALUATION OF REPLIES. IT MAY BE SET TO 200 OCTAL (INTERNAL FOR SPACE) TO ALLOW SYMBOLIC EVALUATION. THIS INCLUDES ENTRY OF OCTAL NUMBERS. BEWARE OF SIMPLE "ASK" OF OCTAL NUMBERS HOWEVER, SINCE THE "@" SIGN WILL BE TAKEN FOR AN INDIRECT. SET &%(1) TO @100 INSTEAD TO READ OCTAL NUMBERS. THE SECOND ELEMENT OF THIS VECTOR, I.E. &%(2), IS THE TERMINAL OR OPERATE OUTPUT WIDTH (MAXIMUM). AFTER THIS NUMBER OF CHARACTERS OF TYPING, FOCAL WILL GENERATE A C.R./L.F. COMBINATION AUTOMATICALLY (THOUGH NOT FOR FCHR OUTPUT). THE ASSEMBLY PARAMETER TTWIDV INITIALLY SETS THIS NUMBER. FOR LIMEPRINTER OUTPUT VIA THE "OPERATE L" COMMAND, SETTING THIS TO 132 MAY BE DESIRABLE. TO DEFINE A GLOBAL AREA WITH VARIABLES, ALL YOU NEED IS A READ/WRITE AREA WITH THE NECESSARY SPACE, AND ANY VECTORS PRE-ALLOCATED. YOU MAY LEAVE THE FOCAL FLOATING-POINT VARIABLES BLANK AND INITIALIZE THEM AT THE FIRST USE OF THE COMMON. NOTE THAT ALL FOCAL VARIABLES (EVEN IN A GLOBAL COMMON) MUST BE IN READ/WRITE MEMORY. CODE TO DEFINE A COMMON AREA FOR USE WITH FOCAL MIGHT THEN LOOK LIKE THIS FOR THE CASE OF 1024 VARIABLES (4 WORDS EACH): .PSECT MYSECT,RW,D GBCDB:: .BLKW 4*1024. GBCDE:: TO INITIALIZE THE AREA TO CONTAIN THE ARRAY ZZ(0) - ZZ(1023), EXECUTE THE FOLLOWING COMMAND BEFORE ANY VERSION OF FOCAL USING THE COMMON HAS BEEN RUN: MCR>FCL F &A=0,1023;S ZZ(&A)=0 THIS WILL SET UP THE ARRAY ZZ INTO THE COMMON, WHERE IT WILL REMAIN THEREAFTER. IF ANY VECTORS HAVE BEEN ALLOCATED (STARTING AT THE BEGINNING OF THE COMMON AREA), THEY WILL BE SKIPPED. NOTE THAT VARIABLES IN GLOBAL COMMONS DO NOT APPEAR IN THE "TYPE $" SYMBOL TABLE DUMP. IF ANY DO, YOU KNOW THEY DID NOT GET INTO THE GLOBAL COMMON. ALARMS (CLOCK INTERRUPTS) FOCAL ALLOWS IN ADDITION TO INTERRUPTS THE ABILITY TO HAVE UP TO 8 SEPARATE PSEUDO-INTERRUPTS GENERATED BY CLOCK OPERATIONS USING THE RSX11D ASYNCHRONOUS SYSTEM TRAP (AST) FEATURE. THE NUMBER OF ALARMS MAY BE SET BY THE ASSEMBLY CONDITIONAL "NFAKES" WHICH MUST BE 3 OR MORE AND DEFAULTS TO 8. THE LEGALITY CHECK WILL FAIL (ERROR 49 CALLED) IF THE ALARM NUMBER IS ILLEGAL. WHILE THE SYSTEM MAY NOT BE TOO CONFUSED IF YOU SPECIFY MULTIPLE ALARMS FOR THE SAME ALARM NUMBER, FOCAL WILL; SET A NEW ALARM IN THE INTERRUPT SERVICE GROUP IF YOU WANT TO SET ONE. ALARMS HAVE HIGHER SOFTWARE PRIORITY THAN ANY HARDWARE INTERRUPTS AND ARE TREATED THE SAME BY FOCAL, THOUGH THE FOCAL TASK NEED NOT BE MAPPED INTO THE EXTERNAL PAGE TO USE THEM. (IT MUST HOWEVER BE ASSEMBLED WITH "EPACC" DEFINED TO HAVE THIS FEATURE). TO SCHEDULE AN ALARM, CALL FALRM WITH THE APPROPRIATE INPUTS. ANY OR ALL OF THESE ALARMS MAY BE ACTIVE AT A GIVEN INSTANT, AND INTERRUPTS MAY BE AS WELL. NOTE THAT FOCAL MUST BE ASSEMBLED TO PERMIT MULTIPLE INTERRUPTS TO ALLOW ALARMS. NOTE THAT FOCAL WILL ATTEMPT ON EXIT TO DISABLE ANY PENDING INTERRUPTS BY MOVING THE WORD INTO THE DEVICE CSR. IF IT CANNOT DO SO (EXTERNAL COMMON NOT UNDER APR7), IT WILL EVENTUALLY MANAGE TO EXIT ANYWAY, AS IT CLEARS ITS FLAG FIRST. AT MOST 16 TRIES TO GET RID OF FOCAL WILL BE NEEDED. (HINT: IT'S BEST TO PUT THE EXTERNAL COMMON AT 28K-32K.) 4. FCLK FCLK RETURNS THE NUMBER OF SECONDS SINCE MIDNIGHT NOW, GETTING THE TIME VIA A GTIM$ CALL TO RSX. A DATE FUNCTION "FDAY" HAS BEEN ADDED ALSO WHICH RETURNS DAY+(32*MONTH*(16*YEAR)) TO ALLOW YOU TO DISPLAY THE DATE. 5. INTEGER ARRAYS FOCAL SUPPORTS INTERNALLY A DATA TYPE OF INTEGER "VECTOR" ARRAYS WHICH MUST BE PRE-ALLOCATED BEFORE USE. THESE ARRAYS MAY BE OF ANY LENGTH AND ARE DISTINGUISHED BY HAVING THE ARRAY NAME'S SECOND CHARACTER THE PERCENT SIGN (%). THUS, LEGAL NAMES WOULD BE A%,B%,C%,G%,H%,Q%, ETC. ONLY ONE DIMENSION IS AVAILABLE IN THESE ARRAYS AND THE DATA IS 16-BIT INTEGERS. THE INITIALIZING IS DONE BY THE VECTOR DECLARATION STATEMENT, WHOSE FORM IS AS FOLLOWS: VECTOR R(45) WHERE THE VARIABLE R% IS IN THE EXAMPLE DIMENSIONED AS 45 LONG. DIMENSIONS ARE POSITIVE AND START AT ZERO (0). THUS, V R ALLOCATES A ONE-WORD "ARRAY" R% OF LENGTH 1 WORD. NOTE THAT NO CHARACTERS OTHER THAN SPACE MAY FOLLOW THE V HERE AND THE FORM MUST BE FOLLOWED EXACTLY. A SECOND FORM OF THE "VECTOR" STATEMENT ALLOCATES SPACE FOR ALL VECTORS. THIS MUST BE USED PRIOR TO ANY VARIABLE ALLOCATION (OR IMMEDIATELY AFTER AN "ERASE") TO SAVE SPACE FOR ALL VECTORS. THE ALLOCATION IS IN WORDS, BUT BE AWARE THAT THE VECTORS WILL CONTAIN ABOUT 10 EXTRA WORDS EACH FOR OVERHEAD. ERROR 44 IS CALLED WHENEVER YOU EXCEED THE ALLOWED SPACE. THE FORM OF THE STATEMENT TO ALLOCATE SPACE IS JUST VECTOR 500 TO ALLOCATE 500 WORDS OF SPACE FOR VECTORS (WORD=16 BITS). AS AN ADDITIONAL AID, VECTOR ELEMENT 0 WILL BE FILLED IN WITH THE ADDRESS (VIRTUAL) OF VECTOR ELEMENT 1. THIS MAY AVOID A LOT OF CALLS TO FADR IF YOU REMEMBER TO USE VECTOR ELEMENTS 1 TO N RATHER THAN 0 TO N. THIS DATA TYPE IS FOR USE BY ASSEMBLER FUNCTIONS ADDED TO FOCAL WHICH WILL BE ABLE TO OPERATE DIRECTLY ON THE DATA WITHOUT USING THE (RATHER SLOW) FOCAL MATH PACKAGE. HOWEVER, FOCAL CAN ACCESS THESE ARRAYS ALSO. THE SYMBOL TABLE PRINTOUT ROUTINE DOES NOT PRINT THE ENTIRE ARRAYS OF THIS TYPE. A FAST FOURIER TRANSFORM FUNCTION MAY BE TRIVIALLY CONSTRUCTED USING A 16-BIT FFT SUBROUTINE AND THIS DATA TYPE, TO OPERATE ON DATA COLLECTED OR READ INTO SUCH ARRAYS. SOME FUNCTIONS ADAPTED TO HISTOGRAMMING ARE PROVIDED STANDARDLY, THOUGH THESE MAY BE REMOVED BY DEFINING APPROPRIATE ASSEMBLY CONDITIONALS IF DESIRED. NORMAL FOCAL VARIABLES ARE STORED AT HIGH ADDRESSES IN THE FORMAT NAME (ASCII) SUBSCRIPT (1 WORD OR 2 BYTES) EXPONENT AND LOW MANTISSA HIGH MANTISSA WITH SIGN INTEGER ARRAYS ARE STORED IN THE FORMAT NAME (ASCII, 2ND CHAR IS "%") SUBSCRIPT (1 WORD) MAXIMUM SUBSCRIPT ALLOWED DATA 0 (INITIALLY ADDRESS OF DATA 1) DATA 1 (BYTE 1 IS VECTOR(1) IN BYTE ADDRESSED VECTOR; BYTE 0 UNUSED) DATA 2 . . . DATA (MAX SUBSCRIPT) WHEN "GETVAR" IS CALLED TO FIND THE VARIABLE, IT RETURNS WITH R2 (PTR) POINTING AT THE MAXIMUM SUBSCRIPT ENTRY OF THE INTEGER ARRAY OR AT THE EXPONENT AND LOW MANTISSA WORD OF THE FLOATING POINT DATA ARRAY. 5A. STRINGS STRINGS ARE IMPLEMENTED IN FOCAL AS BYTE VECTORS. IT IS POSSIBLE TO CONVERT ANY VECTOR TO A BYTE-SUBSCRIPTED VECTOR OR BACK TO AN INTEGER- SUBSCRIPTED ONE. TO CONVERT TO A BYTE SUBSCRIPT SCHEME, USE: VECTOR "V% TO CONVERT TO A WORD SUBSCRIPT, USE: VECTOR #V% BYTE SUBSCRIPTS START AT 1 (0 RETURNS WORD 0, NORMALLY THE VECTOR ADDRESS.) WORD SUBSCRIPTS START AT 0, BUT IT IS ADVISABLE TO MAKE THEM START AT 1 TO LEAVE THE ADDRESS INTACT. THE FIRST BYTE OF A BYTE VECTOR (V%(1)) IS THE 3RD BYTE OF THE INTEGER VECTOR, AS WORD 0 AND BYTE 0 OF WORD 1 ARE RESERVED. NORMALLY THIS IS NOT A PROBLEM. THE 'HOLLERITH' STATEMENT WILL CONVERT A VECTOR TO BYTE ADDRESSING. YOU MAY TYPE AN ENTIRE VECTOR BY A COMMAND: TYPE 'V%' WHERE THE SINGLE QUOTE (') IS THE SPECIAL CONTROL. MOST STRING FUNCTIONS DON'T CARE WHETHER A VECTOR IS BYTE ADDRESSED OR NOT--THEY ACT AS THOUGH IT WERE. STRING VECTORS INTERNALLY HAVE THE 200 BIT OF THEIR FIRST CHARACTER SET TO 1, THOUGH THIS WILL NOT SHOW UP ON ANY CONSOLE OUTPUT. THIS IS TRUE WHETHER OR NOT YOU HAVE CHOSEN THE "BASIC-TYPE" SYMBOL TABLE CONDITIONAL ASSEMBLY (EXSYM). 6. RSX CONSOLE CONSIDERATIONS SOME SPECIAL CONSIDERATIONS APPLY FOR *MODIFY*: THE SPECIAL KLUDGES FOR MODIFY ARE THESE: 1. SINGLE C.R. IS THE NORMAL LINE TERMINATOR, SO THAT NEEDS NO SPECIAL ACTION. 2. VERTICAL TABS WILL BE IGNORED IN ALL CASES ON INPUT. 3. UNDERBAR (_) IS THE RESTART CHARACTER, NOT CTL-C. 4. SINCE GCML$ ABSORBS MOST CONTROL CHARACTERS, YOU MUST TYPE IN & INSTEAD OF FORMFEED AND USE : (COLON) INSTEAD OF CONTROL-G. LINE-FEED IS STILL LINE-FEED; ONE HOPES TT16 PASSES IT. 5. SINCE RSX EATS THE RUBOUTS YOU TYPE, YOU CAN ENTER AN EFFECTIVE RUBOUT TO FOCAL BY TYPING "\" (BACKSLASH) WHICH HAS THE SAME EFFECT. NOTE THAT ALTMODE IS NOT CHANGED, SO IF YOUR CONSOLE GENERATES ALTMODE (ASCII 175) INSTEAD OF ESCAPE (ASCII 33), FOCAL WILL NOT UNDERSTAND IT. YOU CAN ALTER THE FOCAL TABLE EASILY AT THE TABLE "SPECIAL" TO CHANGE THIS. THUS THE FORMAT FOR THE MODIFY COMMAND IS: MODIFY (LINE NUMBER)<\\ OR INSERT CHARACTERS> WHERE A BACKSLASH DELETES 1 CHARACTER BACK FROM THE SEARCH CHARACTER AND OTHER TYPED CHARACTERS GO IN AFTER THE SEARCH CHARACTER. MULTIPLE SEARCH CHARACTERS (WITH : BEFORE EACH) ARE PERMITTED TO POSITION THE EDIT SEARCH IN A LINE. THE CHARACTER SEARCHED FOR IS FOUND AND THE FOCAL "POINTER" IS POSITIONED JUST PAST IT. COLON (:) LOOKS FOR THE NEXT OCCURRENCE OF THE SEARCH CHARACTER. MATH IS DONE IN 2-WORD FORMAT, WITH AN 8-BIT SIGNED EXPONENT AND A 24-BIT SIGNED MANTISSA, BUT WITHOUT HIDDEN-BIT NORMALIZATION. THUS, IT IS SLIGHTLY LESS PRECISE THAN THE CONVENTIONAL SINGLE-PRECISION ARITHMETIC OF FORTRAN. ALL MATH IS DONE IN SOFTWARE, AND WILL WORK ON ANY PDP11. NOTE THAT FOCAL USES IOT AND THE ILLEGAL INSTRUCTION TRAP FOR COMMUNICATION AS WELL AS THE TRAP INSTRUCTION. MOST INTERNAL FOCAL CALLS ARE BY SUBROUTINE CALLS (JSR) INSTEAD OF TRAPS TO SPEED IT UP UNDER RSX. HOWEVER, TRAP CALLS ARE STILL LEGAL. FLOATING POINT TRAPS MAY BE EITHER ILLEGAL INSTRUCTIONS OR NON-RSX EMT'S. 7. FUNCTIONS AVAILABLE IN FOCAL FAND(I,J)--AND OF I,J FIOR(I,J)--IOR OF I,J FADR(SUBSCRIPT, VARIABLE)--ADDRESS OF VARIABLE. (N.B.--FOR FLOATING NUMBERS, USE FADR(SUB,VAR(SUB))) FRCHR(CODE)--READ/WRITE ASCII IN REAL TIME. IF CODE IS NEGATIVE, READ A CHARACTER. RETURN CHARACTER IF DONE, -1 IF BUSY. IF CODE IS POSITIVE, PRINT 7 BIT CODE, RETURN 1 WHEN DONE, -1 WHEN BUSY. FEXP--EXPONENTIAL (BASE E) FLOG--NATURAL LOGARITHM FATN--ARC TANGENT (RADIANS) FSQT--SQUARE ROOT FSIN(X)--SINE OF X, X IN RADIANS FCOS(X)--COSINE OF X, X IN RADIANS FITR(X)--INTEGER PART OF X FSGN(X)--SIGN PART OF X FSBR(GROUPNO, ARG)--EXECUTE GROUPNO WITH ARG AS CALLED, AS A SUBROUTINE. IN THE SUBROUTINE THE VARIABLE & IS THE INPUT ARGUMENT AND THE VALUE RETURNED IS THE LAST VALUE OF &. NOTE THAT RECURSIVE CALLS TO FSBR ARE LEGAL AND A NEW & WILL BE GENERATED FOR EACH LEVEL. FRAN(X)--RANDOM NUMBER BETWEEN -1 AND +1 FADC(ARG,ARG,ARG,...ARG)--FAST EVALUATION OF ARGUMENT LIST. (THIS IS USEFUL IF YOU HAVE FUNCTIONS LIKE THE HISTOGRAM OR FX THAT YOU WANT FOCAL TO EVALUATE QUICKLY IN A LIST. THIS FUNCTION WILL SIMPLY EVALUATE THEM AND RETURN THE VALUE OF THE LAST OF THEM, SOMEWHAT FASTER THAN WOULD BE DONE IN SEPARATE STATEMENTS OF THE INTERPRETER. FX(2,BUSS.ADDR)--READ WORD FX(-2,BUSS.ADDR,DATA)--WRITE WORD FX(1,BUSS.ADDR)--READ BYTE FX(0,BUSS.ADDR, DATA)--"AND" WORD FX(-1,BUSS.ADDR,DATA)--DEPOSIT BYTE (NOTE: YOU MAY DEPOSIT DATA ONLY ABOVE THE TOP OF FOCAL.) FCHR(-1)--READ ASCII CHARACTER FCHR(FOO)--WRITE ASCII CHARACTER FCHR(-1,R,S,T)--1 IN AND 3 OUT. FALRM(ALARM#,DELAY-MAGNITUDE,DELAY UNIT,GROUP)--SET UP ALARM NUMBER 1 TO 3 TO GO OFF AFTER "DELAY-MAGNITUDE" WHERE DELAY UNIT MAY BE 0 FOR TICKS AND 1 FOR SECONDS. CONTROL GOES TO THE FOCAL GROUP GIVEN UPON THE AST. THIS ACTS AS A PSEUDO-INTERRUPT, AND FOCAL MUST BE ABLE TO (TRANSIENTLY) ACCESS THE PSW IN THE EXTERNAL PAGE FOR THIS TO WORK. FINT(PRI,IVA,GROUP,CSR,MASK)--PRESET INTERRUPT HANDLING ON CHANNEL LABELLED BY PRI. (ONLY ONE IVA PER PRI!) FS2H(NUMBER,ADDR)--CONVERT NUMBER INTO PDP-11 HARDWARE FLOATING POINT FORMAT AND STORE AS A 32-BIT NUMBER AT ADDR. THE FUNCTION RETURNS A VALUE OF ADDR+4 TO ALLOW THAT ADDRESS TO BE USED IN CASE A VECTOR IS BEING FILLED SUCCESSIVELY. THE ADDRESS IS TO BE A STANDARD BYTE ADDRESS AS RETURNED BY FADR(SUBSCRIPT, VARIABLE). ("SOFTWARE TO HARDWARE FLOATING CONVERSION") FH2S(ADDR)--CONVERTS THE PDP-11 HARDWARE FLOATING POINT NUMBER AT ADDR INTO A FOCAL INTERNAL FORMAT FLOATING POINT NUMBER AND RETURNS THAT AS THE VALUE OF THE FUNCTION. ("HARDWARE TO SOFTWARE FLOATING CONVERSION") (NOTE THAT THE ASSEMBLY PARAMETER "FPP11" MUST BE DEFINED TO OBTAIN THESE FUNCTIONS. IF IN ADDITION THE PARAMETER "FPP11A" IS DEFINED, FOCAL'S BASIC MATH ROUTINES WILL USE HARDWARE FLOATING POINT.) FCLK() RETURNS NUMBER OF SECONDS SINCE MIDNIGHT FDAY() RETURNS DATE AS DD+16*(MM+32*DD)) IN DAYS. STRING FUNCTIONS (USE WITH BYTE VECTORS) FS2N(SUBSCRIPT 1,VECTOR,LENGTH) CONVERTS THE STRING TO A NUMBER AND RETURNS THE VALUE OF THE NUMBER. IF THE STRING IS NOT FOCAL INTERNAL CODE, ONLY DIGITS WILL BE PROPERLY TREATED. FOCAL INTERNAL CODE HAS THE FOLLOWING CHARACTERISTICS: CHARACTER FOCAL CODE (OCTAL) SPACE 200 + 201 - 202 / 203 * 204 ^ (UPARROW) 205 ( 206 [ 207 < 210 ) 211 ] 212 > 213 , (COMMA) 214 ; (SEMICOLON) 215 CARRIAGE RETURN (ASCII 015) 216 = 217 ALL OTHER FOCAL CODES ARE THE SAME AS THE REGULAR ASCII CHARACTER SET. THE FUNCTION "FTRANS" IS PROVIDED TO ALLEVIATE THIS PROBLEM AND IT WILL TRANSLATE A STRING BETWEEN INTERNAL AND EXTERNAL FORMATS: FTRANS(FUNCT,V%(SUB),LENGTH) TRANSLATES A STRING STARTING IN VECTOR V%(SUB) FOR LENGTH BYTES. IF FUNCT IS 0, IT TRANSLATES ASCII TO FOCAL INTERNAL FORMAT. IF FUNCT IS NON-ZERO, IT TRANSLATES FOCAL INTERNAL FORMAT TO ASCII. FN2S(NUMBER,VECTOR,SUBSCRIPT) MAKES A STRING OUT OF A NUMBER AT VECTOR(SUBSCRIPT). FSTRD(SUB,VECTOR,MAXLEN) READS ASCII INTO A STRING VECTOR STARTING AT SUBSCRIPT SUB. RETURNS LENGTH ACTUALLY READ. FSTWT(SUB,VECTOR,LENGTH) PRINTS TEXT FROM VECTOR FOR LENGTH BYTES. FINDS(SUB1,VECT1,LEN1,SUB2,VECT2,LEN2) LOOKS IN VECTOR VECT2 STARTING AT SUB2 FOR LEN2 BYTES AND TRIES TO FIND THE STRING IN VECT1 STARTING AT SUB1 FOR LEN1 BYTES. IF SUCCESSFUL IT RETURNS THE SUBSCRIPT IN VECT2 OF THE START OF THE MATCHING STRING. OTHERWISE IT RETURNS 0. FCMPS(SUB1,VECT1,LENGTH,SUB2,VECT2) COMPARES THE STRINGS IN VECTORS VEC1 AND VECT2 STARTING AT SUB1 AND SUB2 FOR LENGTH BYTES. IF THEY ARE IDENTICAL, A 1 IS RETURNED. OTHERWISE 0 RETURNS. FMOVB(SUB1,VEC1,SUB2,VECT2,LEN1) MOVES A STRING FROM VEC1 TO VECT2 STARTING AT SUB1 IN VEC1 AND PUTTING THE DATA FOR LEN1 BYTES INTO VECT2 AT SUB2. ****** FUNCTIONS FOR USE WITH VECTOR (%) VARIABLES (INTEGER ARRAYS) FBUS(ADDR) GIVE THE LOW-ORDER 16 BITS OF THE REAL BUS ADDRESS OF THE VIRTUAL ADDRESS 'ADDR' IN THE ARGUMENT. USED FOR SETTING UP I/O WHERE FINT IS TO BE USED ALSO. FBUSH(ADDR) GIVE THE HIGH ORDER 2 OR 6 BITS OF THE REAL BUS ADDRESS OF THE CELL WHOSE VIRTUAL ADDRESS IS GIVEN IN 'ADDR'. THE RESULT IS RETURNED SHIFTED LEFT 4 BITS SO THAT BITS 4 AND 5 (AND 6,7,8,9 ON 11/70) CONTAIN THE EXTENDED ADDRESSING BITS. THIS IS TO CONFORM TO THE USUAL DEVICE REGISTER ARRANGEMENT. FLIM(DAT.ADDR,WC,LO,HI,DEFAULT) TAKE WC WORDS STARTING AT ADDRESS DAT.ADR AND TEST WHETHER THE DATA IS BETWEEN VALUES "LO" AND "HI" (TAKEN AS SIGNED INTEGERS). IF NOT, REPLACE DATA WITH DEFAULT (ALSO A SIGNED INTEGER.) FLIMT(DAT.ADR,WC,LOTBL.ADR,HITBL.ADR,DEFTBL.ADR) WORKS AS FLIM, BUT LO AND HI ARE TABLE ADDRESSES AS IS DEFAULT. WC WORDS STARTING AT ADDR ARE COMPARED WITH VALUES IN CORRESPONDING POSITIONS OF LOTBL AND HITBL AND REPLACED WITH VALUES OF DEFTBL IF NOT BETWEEN THOSE VALUES. FWRD(IN.ADDR,WC,OUT.ADDR) TAKES THE IN.ADDR ARRAY AND FOR WC WORDS PACKS THE LOW BYTE OF THE INPUT ARRAY INTO SUCCESSIVE BYTES OF THE OUTPUT ARRAY (AT OUT.ADDR). THIS IS THE INVERSE OF THE FUNCTION "FBYT". FMHST(DAT.ADR,DAT.WC,HIST.ADR,HIST.WC,LOLIM,SCL) TAKE EACH WORD OF DATA, HISTOGRAM IN SEPARATE HISTOS LOCATED CONTIGUOUSLY IN MEMORY STARTING AT "ADR.HIST" WITH EACH OF THE HISTOS HAVING HIST.WC WORDS AND LOW BIN VALUE LOLIM. SCL IS NUMBER OF TIMES (<=7) TO SHIFT DATA RIGHT BEFORE HISTOGRAMMING. HISTO ARRAY SHOULD BE (HIST.WC)*(DAT.WC) WORDS LONG FOR DATA TO FIT. FHIST(DAT.ADR,DAT.WC,HIST.ADR,HIST.WC,LOLIM,SCL) TAKE MULTIPLE WORDS AND HISTOGRAM IN A SINGLE HISTOGRAM AT GIVEN ADDRESS. SCALE AND LOLIM SAME AS IN FMHST. HISTOGRAM ARRAY SHOULD BE HIST.WC WORDS LONG. FASR(ADDR,WC)--DOES ASR ON WHOLE ARRAY FASL(ADDR,WC)--DOES ASL ON WHOLE ARRAY FBYT(ADDR.IN, # CHARS,ADDR.OUT)--COPIES BYTES FROM INPUT ARRAY INTO LOWER BYTE OF WORDS OF OUTPUT ARRAY. UPPER BYTES OF OUTPUT ARRAY ARE ZERO. FMOV(IN.ADDR,WC,OUT.ADDR)--MOVES DATA FROM INPUT ARRAY TO OUTPUT ARRAY FOR WC WORDS. FPLT(ADDR, NWORDS)--PLOTS A PLOT ON THE VERSATEC LINEPRINTER IN PLOT MODE. NWORDS MUST BE 256 OR LESS AND THE VERTICAL SCALE WILL BE ADJUSTED BY A POWER OF 2 UNTIL THE MAXIMUM BIN IS 512. OR LESS. POSITIVE NUMBERS ONLY MAY BE PLOTTED, FROM INTEGER ARRAYS. SCALE MARKS WILL BE DRAWN HORIZONTALLY EVERY BIN LIGHTLY AND DARKER MARKS WILL BE DRAWN EACH 25 BINS. VERTICALLY EVERY 10TH NIB WILL BE MARKED LIGHTLY AND EVERY 100TH MARKED MORE DARKLY. FNIB(NIB)--SETS UP A NIB (0 TO 1023 LEGAL) NUMBERED BY NIB NUMBER AS TURNED "ON" IN THE PLOT BUFFER. FNIB WILL RETURN THE ADDRESS OF THE PLOT BUFFER ON RETURN AS THE FUNCTION VALUE. IT IS 128. BYTES LONG AND MAY BE COPIED BY FMOV OR MODIFIED WITH FX. (CARE MUST BE USED IN THIS IF FPLT IS OVERLAID.) FNIBS(LONIB,HINIB)--SETS THE NIBS FROM LONIB TO HINIB INCLUSIVE AS "ON" IN THE PLOT BUFFER. RETURNS THE ADDRESS OF THE PLOT LINE BUFFER AS FNIB DOES. FPLD()--PLOTS OUT THE LINE BUFFER, THEN CLEARS IT. RETURNS THE VALUE OF THE LINE BUFFER ADDRESS AS FNIB AND FNIBS DO. FOVV(ADDR,WC)-- PLOTS OUT NUMBERS ONCE IN NONSTORE MODE ON VT. THE NUMBERS ARE TREATED AS UNSIGNED OCTAL INTEGERS STARTING AT ADDR AND CONTINUING FOR WC WORDS. ADDR MUST BE LEGAL IN THE FOCAL DATA AREA. NUMBERS ARE PLOTTED VERTICALLY, THAT IS, FROM TOP LEFT DOWN, THEN ANOTHER COLUMN RIGHT OF THE ONE PLOTTED. ABOUT 300-350 NUMBERS WILL FIT ON THE SCREEN, BUT FLICKER IS BAD FOR MORE THAN ABOUT 50. MAY BE CALLED REPETITIVELY. FDVV(ADDR,WC)-- AS FOVV EXCEPT NUMBERS ARE PLOTTED IN DECIMAL INSTEAD OF OCTAL FOV(ADDR,WC)-- AS FOVV EXCEPT NUMBERS ARE PLOTTED ACROSS IN ROWS RATHER THAN DOWN IN COLUMNS. FDV(ADDR,WC)-- AS FOVT BUT NUMBERS ARE IN DECIMAL FLODM(MBD #)-- LOADS MBD-11 WITH CODE FOR LATER USE. TO USE MBD, CALL THIS FUNCTION FIRST, THEN USE FINT TO SET UP MBD INTERRUPT VECTOR AND FCNA AND FCMDB TO SET UP CONTROL BLOCKS. THEN USE FX TO PUT THE ADDRESS OF THE CONTROL BLOCK INTO THE MBD'S PDX REGISTER AND PUT A COMMAND TO INITIALIZE THE DESIRED CHANNEL INTO THE MBD'S CSR. THE CONTROL BLOCK, WHICH MAY BE SET UP WITH THE AID OF FCMDB, TELLS THE MBD WHAT TO DO. THIS MBD CODE IS BASICALLY THE LAMPF "MBDSTD" CODE. COMMAND CHAINING IS USABLE BY USING FX TO FINISH COMMAND BLOCK SETUP. MBD1 IS ASSUMED TO HAVE CSR ADDR 764400; MBD2 HAS CSR ADDR 764440. INTERRUPT VECTORS ARE 400-540 AND 600-740. FCNA(FUNCTION,CRATE,STATION NUMBER, SUBADDR) RETURNS A VALUE EQUAL TO THE MBD'S EXPECTED FORMAT FOR CAMAC COMMANDS. CRUDE RANGE CHECKS ARE PERFORMED TO ENSURE NUMBERS ARE IN RANGE, AND ERROR 40 IS CALLED IF THEY ARE NOT. A CAMAC FUNCTION BLOCK CONSISTS OF A SET OF INTEGERS IN THE FORMAT DELIVERED BY FCNA TERMINATED BY A ZERO. THE ADDRESS OF THE BLOCK SHOULD BE 1 WORD BEFORE THE FIRST NUMBER. THUS, IF THE VECTOR C% CONTAINS THE CAMAC COMMANDS, C%(1) SHOULD BE THE FIRST ACTUAL CAMAC COMMAND, AND C%(0) SHOULD BE SPECIFIED (I.E., FADDR(0,C%)) AS THE NUMBER TO GET THE ADDRESS OF FOR THE BLOCK ADDRESS. FCMDB(ADDR,CODE,BUFAD-2,WC,FCNAD-2)--SETS UP A LEGAL MBD COMMAND BLOCK AT THE ADDRESS ADDR. THE NUMBERS IN IT HAVE THE FOLLOWING SIGNIFICANCE: ; 1.CODE 1--READ 16-BIT DATA 2--READ 24-BIT DATA 3--WRITE 16-BIT DATA (IE, PDP11 TO CAMAC) 4--WRITE 24-BIT DATA 5--ISSUE CONTROL/TEST INSTRUCTIONS 6--MBD-PDP11 OR PDP11-MBD MEMORY-MEMORY TRANSFER THE HIGH BYTE OF THE CODE WORD MAY HAVE BIT 12 ON IF STOP AFTER Q=0 BIT 13 ON IF AWAIT 2ND LAM FOR 2ND AND FOLLOWING COMMANDS BIT 14 ON TO REPEAT FCNA LIST WHENEVER IT IS EXHAUSTED BIT 15 ON FOR LAM-INITIATED SEQUENCE OF CAMAC COMMANDS 2. DATA BUFFER ADDRESS -2 THIS IS THE ADDRESS OF THE DATA BUFFER -2 (SO USE SUBSCRIPT 0 AS IN THE FCNA LIST ABOVE). IT IS REQUIRED EVEN FOR CONTROL/TEST INSTRUCTIONS; THE MBD RETURNS SOME DATA THERE THEN. 3. WC---WORD COUNT THIS IS THE NUMBER OF WORDS FOR THE MBD TO TRANSFER (MAX) FOR THIS CONTROL BLOCK. 4. FCNAD-2 THIS IS THE FCNA LIST ADDRESS -2 (AS SAID ABOVE ALREADY). IT GIVES CAMAC COMMANDS (MINUS BIT 8, WHICH IS IMPLIED BY CODE) AND MUST BE TERMINATED BY A ZERO. (NOTE THE VECTOR COMMAND ZEROES THE VECTOR PRIOR TO USE, SO ANUNINITIALIZED ELEMENT WILL ALREADY CONTAIN 0. ; AFTER THESE WORDS, THE CONTROL BLOCK HAS 3 MORE WORDS WHICH ARE ZEROED BY FCMDB. THEY ARE THE REMAINING WORD COUNT (SET BY MBD IF WC IS NOT EXHAUSTED), THE CHAIN ADDRESS (SET TO 0 HERE), AND THE MAILBOX IN WHICH THE MBD SETS UP BITS TO INDICATE ABNORMAL CONDITIONS. THESE WORDS NEED NOT BE USED, BUT MUST BE RESERVED IN THE COMMAND BLOCK ARRAY OR THE PROGRAM WILL MALFUNCTION. FHS(ADDR)--PLOTA INTERFACE TO USER. ADDR IS THE ADDRESS OF A BLOCK OF ARGUMENTS TO PLOTA WHICH MUST BE SET UP AND ITS ADDRESS PASSED TO FHSS. THE ARGUMENTS THEMSELVES ARE ALL ARRAYS, AND THE BLOCK LOOKS LIKE THIS: ADDR IS THE ADDRESS OF BLOCK: BLOCK(0)--ADDRESS OF INIT ARRAY(DIM=6) BLOCK(1)--ADDRESS OF IBOX ARRAY(DIM=4) BLOCK(2)--ADDRESS OF ILIM ARRAY(DIM=9) BLOCK(3)--ADDRESS OF ITIX ARRAY(DIM=2) BLOCK(4)--ADDRESS OF IPAR ARRAY(DIM=3) BLOCK(5)--ADDRESS OF ISYM ARRAY(DIM=1) NO CHECKING IS PERFORMED ON ANY OF THESE ADDRESSES. BEWARE. FORMAT OF THE ARRAYS: INIT(1) BITS 15-0 ARE AS FOLLOWS 15 ERASE/OVERPRINT 14 NEW PLOT/OLD PLOT (IF 1/IF 0) 13 ROUND YMAX,YMIN /NO ROUNDING 12 ROUND XMAX/XMIN/NO ROUNDING 11 FIND YMAX/GIVE YMAX 10 FIND YMIN/GIVE YMIN 9 FIND XMAX/GIVE XMAX 8 FIND XMIN/GIVE XMIN 7 DRAW X SCALE/NO X SCALE 6 DRAW Y SCALE/NO Y SCALE 5 PRINT PARAMETERS/NO PARAMETERS 4 PRINT TITLE/OMIT TITLE 3 PRINT X UNDER/OVERFLOW/NO OVER-UNDER-FLOW 2 PRINT Y OVER-UNDERFLOW/NO Y OVER-UNDERFLOW 1 UNUSED 0 INDEX ENTRY /NOT IN INDEX (UNUSED) SUGGESTED VALUE: @165300 INIT(2) BITS ARE AS FOLLOWS: 15 LOG/LINEAR 14 LARGE/SMALL LETTERS 13-12 UNUSED 11-9 DISPLAY MODE 0-ILLEGAL 1-HISTOGRAM 2-LINE GRAPH 3-SCATTERGRAM 4-SYMBOL PLOT 5-CORRELATION PLOT 6,7--ILLEGAL 8 UNUSED 7-6 ERROR DISPLAY 0-NO ERRORS 1-ERROR IS SQRT(Y) 2-ERROR IS VALUE IN ERROR ARRAY 3-ERROR IS SQRT(VALUE IN ERROR ARRAY) 5-3 STORAGE FORMAT 0-Y'S ONLY 1-(X,Y) PAIRS 2-X AND Y ARRAYS 3-ILLEGAL 4-(Y,ERROR) PAIRS 5-(X,Y,ERROR) TRIPLETS 6-X,Y, AND ERROR ARRAYS 7-ILLEGAL 2-1 UNUSED 0 DOUBLE WORD/SINGLE WORD (1 OR 0) SUGGESTED VALUE: @101000 INIT(3) IS THE NUMBER OF POINTS TO BE PLOTTED INIT(4) IS FIRST ADDRESS OF DATA BUFFER OF Y ARRAYS EXCEPT IN FORMATS 2 AND 6, WHER IT IS THE FIRST ADDRESS OF THE X ARRAYS INIT(5) IS THE FIRST ADDRESS OF Y ARRAY FOR FORMATS 2 AND 6. OTHERWISE IGNORED. INIT(6) IS THE FIRST ADDRESS OF THE ERROR ARRAY FOR STORAGE FORMAT 6. OTHERWISE IGNORED. IBOX(1)--DIMENSION OF GRAPH ALONG VT01 CRT IN RASTER UNITS (SCREEN IS 2048 BY 2048). SUGGESTED VALUE: 1700. IBOX(2)--HORIZONTAL OFFSET TO LOWER LEFT OF GRAPH. RECOMMENDED VALUE: 275. IBOX(3)--DIMENSION OF GRAPH VERTICALLY. SUGGESTED VALUE: 1700. IBOX(4)--VERTICAL OFFSET UP TO BOTTOM OF GRAPH. SUGGESTED VALUE: 200. ILIM(1) IS MAXIMUM X VALUE ON GRAPH ILIM(2) IS MINIMUM X VALUE ILIM(3) IS MAXIMUM Y VALUE ILIM(4) IS MINIMUM Y VALUE THESE APPLY ONLY IF BITS IN INIT(1) ARE SET TO CAUSE THEM TO BE USED. ITIX(1) IS THE NUMBER OF HORIZONTAL TIK MARKS ALONG BORDER ITIX(2) IS NUMBER OF VERTICAL TIK MARKS. (THESE ARE NUMBER OF XBINS OR YBINS FOR CORRELATION PLOTS.) IPAR(1) IS NUMBER OF PARAMETERS TO PRINT AT THE TOP OF THE GRAPH. IPAR(2) IS THE FIRST WORD OF PARAMETER WORD LIST. EACH IS 3 WORDS OF ASCII SOMEWHERE IPAR(3) IS FIRST ADDRESS OF THE PARAMETER VALUE LIST. NOTE THAT VALUES MUST BE INTEGERS. PLOTA DOES NOT UNDERSTAND FOCAL'S FLOATING-POINT NUMBERS. ITLE(1) IS NUMBER OF CHARACTERS IN TITLE ITLE(2) IS FIRST ADDRESS OF TITLE. (70 CHARS MAX.) ISYM IS AN ASCII SYMBOL USED IN SYMBOL PLOT. (TRY @53 [+]) FBDGO(CONTROL-BLOCK-ADDRESS, CHANNEL NO.)--STARTS MBD BY PLACING CONTROL BLOCK ADDRESS INTO PDX AND INITIALIZE COMMAND FOR THE CHANNEL NUMBER INTO THE CSR. THE INTERRUPT IS (MUST BE) ENABLED HERE FOR THE MBD. THIS FUNCTION IS USEFUL FOR TWO REASONS: FIRST, IT MAKES IT UNNECESSARY TO REMEMBER THE FORMAT OF THE MBD CHANNEL INITIALIZE COMMAND AND THE MBD REGISTER ADDRESSES; AND SECONDLY, IT PREVENTS ANY INTERRUPT DRIVEN PROCESSES FROM INTERFERING WITH THE MBD SETUP SEQUENCE, WHICH CAN HAPPEN IF 2 FX CALLS ARE USED FOR THE PURPOSE. FBDG2(CTLBLK ADDR,CHAN) FUNCTIONS AS FBDGO BUT STARTS MBD2 INSTEAD OF MBD1. ******* THE FOLLOWING CONDITIONALS ENABLE/REMOVE FUNCTIONS: EPACC DEFINED, TURNS ON FBUS,FBUSH, AND FINT. OTHERWISE FINT ALWAYS GIVES ERROR 24 ONEINT DEFINED, GENERATES A FOCAL ABLE TO HANDLE ONLY ONE INTERRUPT VECTOR AND FINT DOES NOT HAVE A PRIORITY ARGUMENT. XCAMFC DEFINED, SUPPRESSES FBDGO,FBDG2,FCNA,FCMDB,, AND FLODM, CAMAC FUNCTIONS FOR THE MBD-11 HANDLER XVRTYM DEFINED, REMOVES FOV,FDV,FOVV, AND FDVV, NONSTOREAGE VT01 NUMBER DISPLAY FUNCTIONS. X$PLTA DEFINED, REMOVES CALLS TO PLOTA, AND HENCE ALL STORAGE- MODE HISTOGRAMS ON THE VT01 (FHSS) XLIMIT DEFINED, REMOVES FLIM AND FLIMT ALSO REMOVES FWRD. $$$AST DEFINED, PRODUCES A FOCAL WHICH PROMPTS FOR COMMAND INPUT WITH * AND FOR ASK INPUT WITH NOTHING (STILL USING GCML$ FOR INPUT IN ALL CASES HOWEVER). IF UNDEFINED, THE FOCAL INTERPRETER WILL PROMPT FOR INPUT WITH THE TEXT "FCL>". FPP11 DEFINED, ENABLES USE OF PDP11 HARDWARE FLOATING POINT FOR THE FUNCTIONS FS2H AND FH2S, BUT NOT FOR FOCAL FLOATING POINT OPERATIONS. IF FLOATING POINT HARDWARE IS PRESENT, THIS IS DESIRABLE. FPP11A DEFINED, CAUSES FOCAL TO USE HARDWARE FLOATING POINT FOR BASIC MATH OPERATIONS. THIS IS NOT RECOMMENDED. TTWIDV DEFINES THE WIDTH OF THE MAXIMUM WIDTH CONSOLE OUTPUT LINE. THIS PARAMETER DEFAULTS TO 80. IF NOT SPECIFIED AT ASSEMBLY TIME, BUT MAY BE MADE AS WIDE AS YOU PLEASE. A POPULAR ALTERNATIVE WIDTH MAY BE 132. FOR USE WITH THE LINEPRINTER. ONLY THE MAXIMUM WIDTH AND THE PLACE WHERE FOCAL WILL INSERT A CR,LF SEQUENCE IN OUTPUT TEXT IS CONTROLLED HERE; SHORTER LINES WILL BE ACCEPTABLE IN ANY CASE. THE INPUT MAXIMUM WIDTH IS 80. IN ALL CASES AND IF A WIDER OUTPUT DEFAULT WIDTH IS USED, CARE MUST BE TAKEN THAT PROGRAMS SAVED MAY BE RE-READ. NFAKES DEFINES NUMBER OF ALARMS PERMITTED. DEFAULTS TO 8, MUST BE AT LEAST 3 NOSTRG DEFINED, REMOVES STRING FUNCTIONS AND BYTE ARRAYS $$SMAL DEFINED, CAUSES FLOATING POINT TRAPS VIA ILLEGAL INSTRUCTIONS RATHER THAN JSR PC,FPPTRP $STERR DEFINED, REMOVES ENGLISH LANGUAGE ERROR MESSAGES. ONLY ERROR NUMBERS ARE THEN REPORTED. NOOJMP DEFINED, REMOVES "JMPON" STATEMENT XLNRNM DEFINED, REMOVES "NUMBER" STATEMENT NOBR.K DEFINED, REMOVES "BREAK" STATEMENT XPAKKK DEFINED, REMOVES "PACK" STATEMENT XVPLOT DEFINED, REMOVES PLOT FUNCTIONS FOR VERSATEC PLOTTER, VIZ.: FNIB,FNIBS,FPLT, AND FPLB XHIST DEFINED, REMOVES FHIST AND FMHST XMOV DEFINED, REMOVES FBYT,FASR,FASL, AND FMOV XRTKB DEFINED, REMOVES FRCHR XUSING DEFINED, REMOVES ALL "USING" STATEMENT I/O CAPABILITY. ******** 8. ERROR HANDLING FOCAL (IF ASSEMBLED WITHOUT $STERR DEFINED) WILL REPORT ERRORS BY PRINTING OUT A CODED ERROR BYTE, AN 8-CHARACTER MESSAGE, AND THE PROGRAM LINE (IF ANY) OF THE ERROR. THE MESSAGES ARE FAIRLY TERSE, BUT GENERALLY WILL REVEAL ROUGHLY WHAT HAS GONE WRONG. SOME ERRORS (NOTABLY THOSE IN THE "USING" COMMANDS) ARE CATCH-ALLS FOR INVALID ENTRIES; FOR THOSE, USE PIP OR OTHER RSX UTILITIES TO FIND OUT WHAT MAY BE WRONG WITH THE FILES IN QUESTION. OTHER ERRORS ARE FAIRLY CLEAR. A RESTART PRODUCES AN ERROR MESSAGE ALSO, BUT THIS IS NORMAL. NEW ERROR CODES MAY BE ADDED, AS ONLY ABOUT 40 OF THE POSSIBLE 63 ARE NOW USED. 9. COMMANDS: (PARTIAL LIST) ASK (ASK "TEXT",N) READ IN N NOTE: A FOCAL EXPRESSION MAY BE ENTERED USING ANY FOCAL VARIABLES OR FUNCTIONS IN REPLY TO ASK. IT WILL BE EVALUATED USING THE CURRENT SYMBOL TABLE. ITS SOLE DISTINGUISHING CHARACTERISTIC IS THAT IT MUST BEGIN WITH + OR -. THIS IS BECAUSE FOCAL NORMALLY (I.E., WITH NO PATCH TO "ASKZER") TREATS ALL ASK INPUT AS THOUGH A 0 WERE IN THE FIRST CHARACTER. THE LEADING + OR - CAUSES THE EXPRESSION TO BE EVALUATED AS 0+EXPRESSION OR 0-EXPRESSION, NOT 0EXPRESSION. BREAK--BREAK OUT OF A *FOR* LOOP. THIS COMMAND CAUSES ONE TO EXIT FROM A "FOR" LOOP WHEN EXECUTED, REGARDLESS OF WHETHER THE LOOP IS FINISHED. CONTROL PASSES TO THE NEXT LINE. COMMENT -NOOP; JUST COMMENT DO--RECURSIVE OPERATION. E.G. DO 2.0--DO ALL LINES IN GROUP 2 UNTIL YOU SEE A "RETURN" COMMAND ERASE--ERASE TEXT OR VARIABLES OR ALL; E (LINE NUMBER), E, OR E A WHERE E (LINE NUMBER) ERASES THE NUMBERED LINE (AND SYMBOLS), "ERASE" ALONE ERASES ONLY SYMBOLS, AND "ERASE ALL" ERASES ALL TEXT AND ALL SYMBOLS. FOR--LOOP CONTROL, ONE LINE. E.G., 1.1FOR Z=1,200;DO 2.0;T Z,! (NOTICE SEMICOLONS SEPARATE COMMANDS IN 1 LINE. ! MEANS CR,LF.) GOTO--TRANSFER CONTROL HOLLERITH-- ENTER TEXT INTO A VECTOR. FORM IS HOLLERITH V%(SUB),"TEXT TO PUT IN"[,SCALAR FOR LENGTH] (E.G., HOLLERITH A%(3),"TEXT FROM SUBSCRIPT 3 ON",LA TO PUT THE STRING INTO A%(3) ON AND THE NUMBER OF BYTES+1 IN VARIABLE LA). IF----LIKE FTN ARITHMETINC IF, BUT IF(EXP)N1,N2,N3 MAY BE TRUNCATED TO IF(EXP)N1,N2 OR IF(EXP)N1. NUMBERS ARE GROUP-LINE NOS. AND DEFAULT IS NEXT COMMAND IF THE "IF" FAILS. JUMPDO--THIS IS A NEW COMMAND SIMILAR TO THE "ON" COMMANDS IN SOME VERSIONS OF FOCAL. IT DOES THE TESTS 'IF' DOES BUT THE CONTROL TRANSFER IS VIA 'DO' RATHER THAN 'GOTO' SO THAT IT IS RECURSIVE. THE USUAL VARIETIES OF 'IF' FORMATS WORK HERE. FORMAT IS J (EXPRESSION) N1,N2,N3 WHERE THE INTERPRETER PERFORMS "DO N1" IF EXPRESSION IS - "DO N2" IF EXPRESSION IS 0 "DO N3" IF EXPRESSION IS + KILL--EXIT FROM FOCAL TO RSX LIBRARY--RSX FILE ACCESS IN C.S.I. FORMAT. THIS HAS 6 SUBFUNCTIONS: 1. LIBRARY R[EAD] DEV:[UIC]FILE.TYP;VER-- READ THE FILE FOR INPUT. THE FILE IS CLOSED IF EITHER AN ENDFILE (OR ERROR) IS SEEN WHILE READING OR IF L C I (LIBRARY CLOSE INPUT) IS SEEN. L C I ALSO DOES RCML$ TO RESET GCML$ INPUT TO TOP LEVEL. NOTE THAT THE INPUT READIN WILL NOT ACTUALLY BEGIN UNTIL AN "OPERATE A" COMMAND IS GIVEN, AND WILL TERMINATE ON AN "OPERATE K", THOUGH THE FILE WILL REMAIN OPEN UNTIL A LIBRARY CLOSE INPUT (OR A KILL, WHICH WILL CLOSE THE FILE PRIOR TO EXIT.) 2.LIBRARY OPEN DEV:[UIC]FILE.EXT;VERS--OPENS THE INDICATED FILE FOR OUTPUT BUT DOES NOT WRITE ANYTHING. ONE USES LIBRARY WRITE OR LIBRARY TYPE TO OUTPUT. THE OPERATE COMMAND DOES NOT CLOSE THE OUTPUT FILE, SO IT STAYS OPEN UNTIL LIBRARY C[LOSE] O (L C O) IS DONE. 3. LIBRARY WRITE GG.LL WRITES LINES OF CODE TO LIBRARY FILE IF IT IS OPEN; ERROR IF NO LIBRARY FILE EXISTS. A CALL OF FORM: LIB WRITE 2.0;W 4.0;W 6.2;T "O KT";T ! IS LEGAL AND WILL WRITE ALL THE INDICATED LINES OF PROGRAM AND TYPE THE TEXT ONTO THE LIBRARY FILE. OUTPUT RETURNS TO THE CONSOLE (OR THE OPERATED FROM *OPERATE* COMMAND) FILE AT THE END OF THE LINE. 4. LIBRARY TYPE TEXT,VARS. FUNCTIONS EXACTLY AS LIBRARY WRITE, EXCEPT IT TYPES TEXT ON THE LIBRARY FILE. THE FORM "LIBRARY TYPE "HELLO"!;W A;S D=D+1" WILL WORK AND OUTPUT EVERYTHING TO THE LIBRARY FILE. THE ONLY WAY YOU CAN OUTPUT TO THE CONSOLE IN THE MEANWHILE IS VIA *OPERATE*, SEE BELOW. 5. LIBRARY CLOSE INPUT OR OUTPUT. THIS COMMAND HAS 3 FORMS: LIBRARY C I ;CLOSE INPUT FILE IF OPEN, NO ERROR FLAGGED IF IT WAS NOT. LIBRARY C O ;CLOSE OUTPUT FILE IF OPEN. NO ERROR ;FLAGGED IF NOT. LIBRARY C IO ;CLOSE BOTH IF BOTH WERE OPEN. IF INPUT ;WAS NOT OPEN, OUTPUT IS NOT CLOSED. ;IF OUTPUT IS NOT OPEN, ONLY INPUT IS ;CLOSED. NOTE THAT YOU MAY NOT SPELL OUT "CLOSE". 6. LIBRARY ERASE DEV:FILE.EXT[UIC]--DELETES THE NAMED FILE. NOTE: SOME LIBRARY FUNCTIONS REQUIRE THAT TEXT AFTER "LIBRARY" BE ABBREVIATED TO A SINGLE CHARACTER PER KEYWORD. CLOSE, OPEN, AND READ AND ERASE ARE IN THIS CATEGORY. 7. LIBRARY XECUTE FNX(ARGS)--EXECUTES THE SPECIFIED FUNCTION WITH THE LIBRARY OUTPUT AS OUTPUT. THIS IS TO MAKE IT EASIER TO USE THE STRING OUTPUT FUNCTIONS OR FCHR FOR OUTPUT TO A LIBRARY FILE. MODIFY--EDITS LINES. SEE ABOVE. NUMBER--AN EDITING COMMAND TO PERMIT YOU TO RENUMBER A LINE. THE SYNTAX IS NUMBER N1,N2 WHERE N1 AND N2 ARE EXPRESSIONS OF THE OLD AND NEW LINE NUMBERS. IF N2 ALREADY EXISTS, ERROR 43 IS CALLED. IF N1 IS NOT A LEGAL NUMBER, ILLEGAL LINE IS CALLED. IF N2 IS ILLEGAL, IT WILL NOT BE USED AND N1 WILL BE LEFT ALONE, BUT NO ERROR WILL BE FLAGGED. ONLY ONE LINE NUMBER MAY BE CHANGED AT A TIME THIS WAY, BUT SINCE THE NUMBERS N1 AND N2 ARE EXPRESSIONS, ONE CAN WRITE A SIMPLE RENUMBERING PROGRAM TO DO THE RENUMBERING. OPERATE--CHANGE I/O DEVICE THE OPERATE COMMAND CHANGES DATASET TO ONE OF SEVERAL DATASETS, DEFAULTING AS FOLLOWS: ONLY OUTPUT MAY BE RE-DIRECTED VIA OPERATE; OPERATE ON DEVICES R,K,A,B,C,D,E, AND F IS RECOGNIZED AND TREATED AS A NO-OP. OUTPUT DEVICE DEFAULTS ARE ON LUNS AS DESCRIBED ABOVE. NOTE THAT OPERATE A WILL CAUSE READIN FROM AN OPEN LIBRARY READ FILE, AND OPERATE K WILL RETURN INPUT TO THE CONSOLE. PACK ADDRESS--TAKE TEXT AT ADDRESS (MUST HAVE C.R. WITHIN 80 BYTES OF ADDRESS) AND PACK INTO CORE AND DO ANY COMMANDS THEREIN. IF NO C.R. WITHIN LIMIT, ERROR 40 RESULTS. CAN BE USED FOR ADDING TEXT TO PROGRAMS OR FOR IMMEDIATE COMMANDS; HOWEVER, ADDING TEXT SOMETIMES ERASES VARIABLES SO USE THAT FEATURE WITH CARE. QUIT--STOP PROGRAM, GET MORE INPUT FROM FOCAL COMMAND INPUT. RETURN--GO BACK TO AFTER "DO" COMMAND SET--ASSIGN VALUE. E.G., SET N=3.4 SET M=FSQT(N) TYPE--PRINT TEXT OR NUMBERS. T !==TYPE CR,LF T $= TYPE SYMBOL TABLE T #= TYPE C.R. ONLY T %9.03= TYPE FLOATING OUTPUT IN FORMAT F9.3 T "TEXT"= TYPE TEXT T A = TYPE NUMBER IN VARIABLE A IN CURRENT FORMAT. (START IS SET TO FORMAT 8.4.) T 'V%'=TYPE ENTIRE STRING IN VECTOR ***** USING: SEE BELOW. THIS PROVIDES REAL-TIME BINARY I/O REAL-TIME I/O INSTRUMENTATION FOCAL ALLOWS UP TO 8 FILES TO BE SIMULTANEOUSLY OPEN FOR BINARY I/O IN ADDITION TO THE 4 PERMITTED FOR ASCII I/O. THESE ARE FOR REAL-TIME DATA TRANSFER TO ANY RSX DATASETS. TO USE THESE FILES, A FOCAL "USING" STATEMENT HAS BEEN PROVIDED. ITS FORMAT IS USING [,ARGUMENTS] THE DATASETS ARE IDENTIFIED BY A SINGLE LETTER OR NUMBER WHICH TELLS FOCAL WHICH DATASET TO USE. THESE DATASETS HAVE VARYING CAPABILITIES TO PERMIT USE OF ANY OF THE I/O LEVELS SUPPORTED BY RSX. THEY ARE DENOTED AS FOLLOWS: LETTER I/O LEVEL DESCRIPTION Q PUT$R/GET$R RANDOM-ACCESS I/O, READ/WRITE TO PREALLOCATED CONTIG FILE (CREATES NEW FILE FOR WRITING) R PUT$R/GET$R RANDOM-ACCESS I/O, R/W TO PREALLOC CONTIG FILE (UPDATES EXISTING FILE, POSSIBLY APPENDING TO IT) S QIO$ SUPERSPEED SEQUENTIAL I/O TO NONFILE DEVICES (R/W) T QIO$ SUPERSPEED SEQUENTIAL I/O TO NONFILE DEVICES (R/W) 1 GET$/PUT$ SEQUENTIAL I/O, READ ONLY, ANY FILE/DEV 2 GET$/PUT$ SEQUENTIAL I/O, READ ONLY, ANY FILE/DEV 3 GET$/PUT$ SEQUENTIAL I/O, WRITE ONLY, ANY FILE/DEV 4 GET$/PUT$ SEQUENTIAL I/O, WRITE ONLY, ANY FILE/DEV NOTE: BY ENLARGING THE TABLES IN THE BEGINNING OF FOCAL, ADDING APPROPRIATE CONTROL BLOCKS, AND LENGTHENING THE LISTS IN THE "USING" PROCESSOR, ONE CAN FAIRLY EASILY ADD MORE FILES OF ANY TYPES. THE OPTION LETTERS AND MEANINGS (ONLY 1 LETTER MAY BE USED, MORE BEING ILLEGAL) ARE AS FOLLOWS: LETTER MEANING FORM R READ USING 2 R,ADDR,WC ;READ WC WORDS INTO MEMORY STARTING ;AT ADDR (FOR D/S 1 AND 2, DATA ;BEGINS AT ADDR+2; THE LENGTH READ ;IS RETURNED AT ADDR.) W WRITE USING 3 W,ADDR,WC ;WRITE WC WORDS FROM MEMORY ADDR TO FILE D DEFINE USING 1 D "DV:[UIC]FILE.TYP;VER" ;DEFINE FILE AND DEVICE ;SHOULD BE DONE PRIOR TO INIT I INIT USING 1 I ;INITIALIZE AND OPEN FILE (ONLY INIT ;FOR QIO$ DATASETS) ; NOTE: FOR DATASETS Q AND R, USE THE ; FORM: "USING Q I,NNN" ; WHERE NNN IS THE BLOCK SIZE IN BYTES OF ; THE FILE. FOCAL WILL ATTEMPT TO ALLOW ;DATASET Q TO CREATE NEW FILES AND DATASET ;R TO UPDATE EXISTING FILES RANDOMLY. C CLOSE USING 1 C ;REMOVES DATASET L LOOP USING 1 L ;LOOP UNTIL ANY I/O COMPLETES T TEST USING 1 T,VAR1,VAR2 ;TEST I/O COMPLETION. VARIABLE ;1 RETURNS WORD 1 OF I/O STATUS BLOCK ;FOR D/S S AND T OR F.ERR OFFSET ;IN FDB FOR OTHER DATASETS. WORD ;2 GIVES 2ND WORD OF I/O STATUS BLK ;FOR QIO$-TYPE DATASETS, RANDOM GARBAGE ;FOR THE OTHERS. BOTH VAR1 AND VAR2 ARE ;REQUIRED. S SPECIAL USING T,S,ADDR ;ADDR IS THE ADDRESS OF AN RSX ;D.P.B. THIS ADDRESS IS CHECKDE ONLY ;FOR BEING EVEN AND NON-ZERO. IT WILL ;BE PUSHED ONTO THE STACK AND ;EMT 377 ISSUED WITH NO FURTHER CHECKS. ;THE DATASET SPECIFIER IS IGNORED, AND ;ANY RSX FUNCTION MAY BE INVOKED. IT IS ;UP TO THE USER TO BE CAREFUL WITH THIS ;FACILITY LEST HE SCREW HIMSELF UP ;ROYALLY. WHERE THE RECORD DATASETS (Q AND R) ARE USED, THE READ OR WRITE OPTIONS HAVE A SLIGHTLY DIFFERENT FORM, VIZ: USING Q R,ADDR,WC,SIZREC,NOREC WHERE W MAY REPLACE R AS THE OPTION. SIZREC IS THE RECORD SIZE IN BYTES, AND NOREC IS THE (16-BIT, UNSIGNED) RECORD NUMBER WITHIN THE FILE. SINCE THESE MODES OF I/O MUST USE PREALLOCATED CONTIGUOUS FILES, ERROR MAY BE FLAGGED BY THE TEST OPTION IF THE RECORD DOES NOT FIT INTO THE FILE BEING USED ON DISK. ALL I/O EXCEPT THAT OF THE QIO$-TYPE DATASETS IS FULLY SYNCHRONOUS THANKS TO DEC'S CONVENTIONS. HOWEVER, THE LOOP COMMAND FOR THE QIO$ DIRECTIVES IS PROTECTED AGAINST INFINITE LOOPS BY A 15-SECOND TIMER THAT FOCAL STARTS. IF THE I/O DOES NOT COMPLETE BY THEN, THE MARKTIME WILL FALL THROUGH AND FOCAL WILL CONTINUE. NO ERROR IS RETURNED. EXAMPLE OF THE "USING" STATEMENTS TO READ PART OF A FILE AND TYPE OUT TEXT IN IT: VECTOR 1000;C:ALLOCATE VECTOR SPACE FIRST VECTOR R(200);S A=FADR(0,R%) VECTOR S(400);S B=FADR(0,S%) USING 1 D "SY:MYFIL.TXT" C:THAT DEFINED FILE. NOW INITIALIZE IT USING 1 I C:NOW READ 200 WORDS. PRESUME THE FILE IS ASCII. USING 1 R,A,200;U 1 L C:THE L CALL GUARANTEES I/O DONE BEFORE PROCEEDING X FBYT(A,400,B);C:UNPACK WORDS TO BYTES IN S% ARRAY FOR G=1,400;X FCHR[S%(G-1)];C:TYPE OUT THE TEXT USING 1 C;C:CLOSE THE FILE. **** VECTOR--DECLARES VECTOR (VARIABLE-SIZE INTEGER) ARRAYS E.G., VECTOR R[55] DECLARES ARRAY R% TO HAVE DIMENSION 55. (DIMENSIONS START AT 0, SO R% WOULD CONTAIN 56 ELEMENTS IF SO DECLARED.) THERE ARE 2 FORMS OF THE 'VECTOR' STATEMENT: VECTOR 500 ALLOCATES 500 WORDS (16 BITS EACH) OF SPACE FOR ALL VECTORS. THIS MUST BE DONE BEFORE ANY VARIABLES ARE ALLOCATED IF VECTORS ARE TO BE USED. THE EXPRESSION AFTER THE "VECTOR" MUST BEGIN WITH A DIGIT, THOUGH A FORM LIKE VECTOR 5+7+3+200 WOULD PROBABLY WORK. VECTOR V(100) ALLOCATES A VECTOR CALLED V% WITH 100 WORDS OF DATA SPACE, AND PUTS THE ADDRESS OF THE VECTOR'S ELEMENT 1 IN ELEMENT 0 SO THAT A REFERENCE TO 'V%' WILL GET THE ADDRESS OF THE VECTOR AND REFERENCES TO V%(1) THROUGH V%(100) WILL GET DATA VALUES IN THE VECTOR. (THIS SAVES REFERENCES TO FADR.) VECTOR "V% DECLARE VECTOR NAMED 'V%' TO BE A BYTE STRING VECTOR VECTOR #V% DECLARE VECTOR NAMED 'V%' TO BE AN INTEGER VECTOR. NOTE: YOU CAN TYPE OUT ENTIRE VECTORS WITH THE FORM: TYPE 'V%' WRITE--LIST ALL OR PART OF A PROGRAM XECUTE--EXECUTE FUNCTIONS--USED WHERE NO VALUE IS NEEDED, AS IN X FCHR(65) TO TYPE AN "A". FOCAL LINE NUMBERS ARE GROUP.LINE EXAMPLES: 1.1 2.2 2.3 2.45 2.54 2.55 LINE NUMBER 0 MEANS THE WHOLE GROUP, SO 1.1 DO 2.0 MEANS TO DO THE ENTIRE SET OF LINES IN GROUP 2. LINES MAY BE ENTERED IN ANY ORDER; EXECUTION IS IN THE ORDER OF THEIR GROUP/LINE NUMBERS. ALL FOCAL OPERATORS MAY BE ABBREVIATED TO A SINGLE CHARACTER. FOCAL ALLOWS VARIABLE NAMES UP TO 2 CHARACTERS LONG (ALPHA, ALPHANUMERIC) AND UP TO 2 DIMENSIONED ARRAYS. ARRAY DIMENSIONS NEED NOT BE DECLARED, AS FOCAL CREATES VARIABLES AS IT SEES THEM SET EQUAL TO SOMETHING. NEGATIVE OR ZERO SUBSCRIPTS ARE LEGAL, THOUGH THE SUBSCRIPTS MUST BE INTEGERS. ONE CAN LIST THE SYMBOL TABLE BY THE COMMAND "T $". IT COMES OUT WITH A "SET" COMMAND PREFIXED SO AFTER WRITING OUT A PROGRAM, YOU CAN USE THE SYMBOL TABLE TYPE TO TYPE CONSTANTS NEEDED ONTO AN OUTPUT FILE. YOU CAN TRACE PROGRAM EXECUTION BY TYPING "?GO" INSTEAD OF "GO" TO START IT. FOCAL PRINTS OUT EACH LINE AS IT INTERPRETS IT, ALLOWING YOU TO DEBUG MORE EASILY. FOCAL ALSO LETS YOU SET A VARIABLE TO A NUMBER AND GO TO THE LINE NUMBERED THAT WAY. NOTE THAT ONLY 2 DECIMALS ARE SIGNIFICANT. WHEN FOCAL ASKS FOR INPUT AND THE FIRST CHARACTER IT SEES IS NUMERIC (EITHER TYPED IN OR BECAUSE ASKZER IS NOT PATCHED TO 200 FROM ITS NORMAL 60), IT CONVERTS SUBSEQUENT ALPHABETIC CHARACTERS TO NUMBERS MODULO 32, EXCEPT FOR E, WHICH IS TREATED AS AN EXPONENTIATION SYMBOL. THUS, A REPLY OF "YES" IS TREATED AS 25. E 19. A REPLY OF "NO" THEN BECOMES 14.*10.+15.*1., OR 155. THESE NUMBERS MAY BE TESTED FOR IN AN "IF" STATEMENT. IF "ASKZER" HAS BEEN PATCHED TO ALLOW EXPRESSIONS TO BE ENTERED, FOCAL DOES NOT TREAT ALPHANUMERIC INPUT AS NUMBERS, BUT WILL IF THE INPUT IS PRECEDED BY 0, I.E., ONE TYPES "0YES" OR "0NO" INSTEAD OF SIMPLY "YES" OR "NO". EXAMPLE: ASK N;IF (N-0YES)2.2,2.3,2.2 (TESTS FOR AN INPUT OF "YES") FOCAL WILL NOT TYPE OUT ":" WHEN ASKING FOR INPUT, AND TYPES SPACE INSTEAD OF "=" WHEN PRINTING A NUMBER. IT ASSUMES A DEFAULT LINE WIDTH OF 80. AND WILL INSERT CARRIAGE RETURN,LF AFTER EACH 80. PRINT POSITIONS. IT WILL OF COURSE DO SO WHEN FORCED TO VIA EXPLICIT PROGRAM CRLF TYPEOUTS. THE FOCAL PROGRAM AREA'S SIZE IS DEFINED BY THE ASSEMBLY PARAMETER "PGMSIZ" WHICH IS ASSEMBLED WITH FCLINIRSX. THIS DEFAULTS TO 4000 WORDS (DECIMAL) AND IS THE AREA FOR FOCAL TEXT AND VARIABLES. RE-ASSEMBLY IS NEEDED TO ENLARGE OR SHRINK THIS AREA. IT IS A GOOD IDEA NOT TO MAKE THE STACK SMALLER THAN THE DEFAULT, EITHER. IT IS EXTENSIVELY USED BY RECURSIVE FUNCTIONS INSIDE FOCAL. IF YOU SEE A LOT OF ERROR 9'S, THAT MEANS THE STACK IS TOO SMALL; REBUILD WITH A BIGGER ONE. RECURSIVE CALLS TO FSBR ARE PERMITTED. THE & VARIABLE WILL BE GENERATED AS OFTEN AS NEEDED TO HANDLE THIS. HERE ARE SOME EXAMPLES: (FROM THE OLD PAPER TAPT FOCAL MANUAL) 10.01C: TAN: FSBR(10,ARG) 10.10 I (&^2-.01)11.2;S &=&/2;D 11;S &=2*&/(1-&^2+1E-20);R 10.20 S &=&+&^3/3+&^5/7.5+&^7/315 11.01C: FACTORIAL FUNCTION FSBR(11,ARG) 11.10 I (1-&)5.2;R 11.20 S &=&*FSBR(5,&-1) 12.01C: ASIN: FSBR(12,ARG) ; ACOS: FSBR(12.3,ARG) 12.10 I (&^2-.01)12.2;S &=&/(FSQT(1+&)+FSQT(1-&));D 12;S &=2*&;R 12.20 S &=&+&^3/6+.075*&^5+&^7/22.4;R 12.30 D 12;S &=1.570796-&;R G. EVERHART, 2/1978