LIBRARY OF THE UNIVERSITY OF ILLINOIS AT URBANA-CHAMPAIGN bi-0 .^4 ttop- & /„ REPORT NO. k66 J7 J<_ July 19 71 ^/AX^ 7 COO-1U69-0188 GRASS: Remote Facilities Guide by R. Haskin J. Nickolls M. Michel NOV 9 1972 UNIVERSITY OF ILLINOIS AT URBANA-CHAMPA1GN DEPARTMENT OF COMPUTER SCIENCE UNIVERSITY OF ILLINOIS AT URBANA-CHAMPAIGN URBANA, ILLINOIS Digitized by the Internet Archive in 2013 http://archive.org/details/grassremotefacil466hask REPORT NO. k66 GRASS: Remote Facilities Guide by R. Haskin J. Nick oils M. Michel July 1971 DEPARTMENT OF COMPUTER SCIENCE UNIVERSITY OF ILLINOIS URBANA, ILLINOIS 6l801 This report supported in part "by the Atomic Energy Commission under grant US AEC AT(ll-l)lU69. Page 1. INTRODUCTION 1 2. INTERACTIVE COMMUNI CATION 2 2.1 Basic Input /Output Facilities 2 2.2 Data Structure Handling Facilities 7 2.3 Extended Input/Output Facilities 11 2.k Creating a Module Using COMMUNE 11 3. LIBRARY MAINTENANCE PROGRAM lk 3.1 Invoking and Terminating LSD lk 3.2 Command Syntax lk 3.3 Commands l6 k. HARDCOPY PRODUCTION 19 k.l Step One: The PLOT Command 19 k.2 Step Two: POT Package 21 LIST OF REFERENCES 2k 1 . INTRODUCTION This report de&crihes facilities that are available to uaers, and to user written programs, running on the remote computer, of the Graphical Remote Access Support System. Familiarity' with, the hasic system and with operation of a terminal is assumed. Consult [l, 2]. The first section describes features that can he called during execution of general user programs on the remote computer. These calls enable convenient Interactive communication between the programs and the terminal. The local program REACT must be executing on the PDP-8 during this time. A facility for performing library file maintenance is described next. This is a program similar to a user program in that it runs on-line in the remote computer under GRASS. It communicates with the user at a terminal via the REACT program, and allows various library operations including saving, deleting, and fetching of files. An important aspect of this program is its use of XFILE macros to access the remote computer library and its use of S8 macros to transmit data to the PDP-8. These two capabilities are also available to user written programs. However, since they are supported by GRASS on a "lower level" than the communication facilities described in the first section, their correct use is very critical. That is, these macros call internal system functions directly; hence, incorrect use, for example, could destroy data in the library or cause transmission difficulties with the PDP-8. Use of these facilities is described in [3]; no use is permitted without prior testing under supervision. A batch test monitor is available for this purpose. The last section describes procedures for producing hardcopy documentation of pictures and mnemonics stored in the library. The requests for hardcopy are ^generated on-line, but the actual plotting is done at a later time by an off-line (batch stream) job. 2. INTERACTIVE COMMUNICATION The PDP-8/36Q Interactive Communications. Package is comprised mainly of two programs; REACT, the generalized communications, program segment which runs in the PDP-8, and COMMUNE, a group of re-entrant routines "which, run in the 3$0. and are callable from user programs running under the GRASS' system. It is assumed that the reader is already reasonably familiar with the use of REACT and the general operation of the graphics terminals. What follows is a full description of COMMUNE and its. use from hoth FORTRAN and assembly language programs. COMMUNE provides the user with routines to perform "basic input/output functions with the terminals, including capability to receive joystick hit coordinate information, to receive text lines typed by the user, and to send text messages to the user. Also, the user has the capability of constructing the elements of pictures (line blocks, text blocks, etc.) and sending them to the PDP-8, either for display or for addition to the user's data structure. 2.1 Basic Input /Output Facilities Three routines comprise the basic text-line-joystick-hit I/O package. These routines are MASK, REPLY, and MESAGE. Two other routines, FINDNM and NUMCHR, aid in interpreting the input from the terminal. Another routine, ERASE, allows the user to erase the display screen and display a frame at any time. MASK MASK provides the user with a way to filter undesired input from the terminal, and to control whether or not user text lines are echoed to the display as they are typed. COMMUNE filters input from a terminal into ten types; 1-9 are joystick hits jn screen segments 1-9 (c.f. Figure l) , and input type 10 is a text line. This filtering can be set up by a call to MASK. The format of a call from FORTRAN is: CALL MASK(IMASK.) IMASK is, an INTEGER*^ array with. 11 elements.. These elements have meaning as follows: IMASK(l) — 1 = do not echo a user-typed text line on the display = echo a user-typed text line IMASK(2) through IMASK(lO) — for screen segments 1-9 1 = accept joystick hit = ignore joystick hit IMASK(ll) — 1 = accept a user-typed text line = ignore a user-typed text line REPLY Input to the user's program from the terminal is performed by calls to REPLY. When REPLY is called, the next input from the terminal (after filtering as per previous calls to MASK) is returned to the program, along vith information as to the input type and length. The FORTRAN calling sequence is: CALL REPLY ( I TYPE, LEN, I DATA, N CHARS) IDATA is an INTEGER*** array with 20 elements. The type and data contained in the input are determined as follows: ITYPE — 1 = input was a joystick hit = input was a user-typed text line LEN — = # of elements of IDATA containing valid data (i.e., if a 12 character text line were returned, LEN would equal 3; for a joystick hit, LEN would also be 3) MESSAGE IDATA-- Fdr a Joystick- Hit IDATA(l) - X coordinate of joystick. hit in increments (from to 1023) IDATA(2) = Y coordinate of hit (0-800) IDATA(3) = screen segment of hit (1-9) For a Text Line IDATA(l)-IDATA(LEN) contain the returned EBCDIC characters packed four per array element. If the total number of characters in the typed text line was not a multiple of four, IDATA(LEN) is padded with blanks to fill out the element. N CHARS — number of text characters sent by PDP-8, before being padded with blanks by EEACT. This parameter is optional and may be omitted if not needed. MESSAGE allows the user to send a text line to the display. The FORTRAN calling sequence is: CALL MESAGE(lTEXT,LEN) ITEXT is an INTEGER*** array having at least (LENA) + 1 elements and containing the EBCDIC characters to be displayed at the terminal, or, optionally, is a character constant. LEN is the number of characters in the message to be displayed. Sample calls are: c C SAMPLE #1 C DIMENSION ITEXTK3) DATA ITEXTl/'SOME JUNK' /,LEN/9/ CALL MESAGE(ITEXT1,LEN) ITEXTl(2)='MOR' ITEXT1(3)='E ' CALL MESAGE(ITEXTl r LEN) STOP END C C SAMPLE #2 C CALL MESAGE ( ' SOME JUNK ' , 9 ) CALL MESAGE ('SOME MORE' ,9) STOP END Both examples result in the lines SOME JUNK SOME MORE being displayed on the terminal. FINDNM, NIMCHR Two routines exist "which allow the user to convert numeric data in his text line to binary. The first of these, FINDNM, scans the array filled by REPLY and determines the location of numeric character strings in the array. NUMCHR is a function subroutine whose input is this character string. It converts the string into a fixed point number and returns it. The calling sequences are: CALL FINDNM(IDATA,IFIRST,ILAST) IDATA is an INTEGER*^ array containing the EBCDIC character string in which the number is to be found (i.e., the IDATA array after a REPLY call). IFIRST and ILAST are the character positions in IDATA (from 1 to 72) between which the number is to be found. Upon return, IFIRST and ILAST contain the character positions of the first and last digits of the first numeric string encountered scanning left to right. If no numeric string is found, IFIRST=ILAST=0 upon return. ERASE ERASE causes the display screen to he erased. Optionally, a frame can he put up also. The FORTRAN calling sequence is: CALL ERASE(IFRAME) IFRAME = for no frame = 1 for frame to he displayed after erase EXAMPLE The code shown "below will display a message, on the user's terminal, to which he responds hy typing in a numher. The number will he converted to an integer value and stored in INUM. DIMENSION IMASK (11) , ITEXT (20) C C SET IMASK TO ECHO TEXT LINES 6 IGNORE J.S. HITS C DATA IMAST/10*0;1/ CALL MASK (IMASK) C C ASK USER TO TYPE IN A NUMBER C 69 CALL MESAGE('TYPE IN A NUMBER' , 16) C C DECODE IT, ITYPE HAS TO BE (TEXT) C 86 CALL REPLY ( ITYPE, LEN , ITEXT,NCHARS) IFIRST = 1 I LAST = NCHARS CALL FINDNM ( ITEXT , IFIRST , ILAST ) C C CHECK IF WE HAVE A REASONABLE NUMBER C IF(IFIRST.EQ.0.OR.ILAST.GT.IFIRST+8) GO TO 69 INUM=NUMCHR (ITEXT , IFIRST , ILAST) 2.2 Data Structure Handling Facilities COMMUNE allows the user to build and send to the PDP-8 line and text blocks. The calls to the routines involved look much like CalComp plotter calls, with the extension that they allow specification of coordinates in either integer or floating point. Options are available to allow the user to erase the display screen, put up a frame, to display or not display the data, and to replace the proper block in the user's current local ( PDP-8) data structure. LINE LINE allows the user to add a line to his current line block. If the block was previously empty, a new one is initialized. The "beam" or "pen" position is moved to the specified coordinates, drawing a line if specified. The X and Y coordinates may be specified either as real or integer values. If real values are supplied, the coordinates are assumed to represent inches on the screen. If integer values are supplied, the coordinates represent screen increments (about 12U.1 increments per inch, 102^ increments across the width of the screen). The FORTRAN calling sequence is : CALL LINE(X,Y,INTEN) or Where CALL LINE(X,Y,INTEN,6STMT) X = X coordinate of line end (either integer or real) Y = Y coordinate of line end INTEN = 1 — draw line from current beam position to (X,Y) — move beam without drawing to (X,Y) 6STMT = optional parameter, indicates the statement number to which control is to be passed (via a RETURN 1 statement) if the line block filled up as a result of this call. LINED LINED is similar to LINE, except X & Y represent differential values to be added to the current beam position to determine the new one. After a call, the new x position will be the previous x + X from this call. TEXT TEXT allows the user to add characters to the text block. If the block was previously empty, a new one is initialized. The FORTRAN calling sequence is : CALL TEXT ( X , Y , TTEXT , LEN ) or CALL TEXT (X , Y , ITEXT , LEN , 6 STMT ) X,Y — fixed or floating coordinates of the text, as in LINE or LINED ITEXT — either a literal constant or the name of an INTEGER* 4 array containing the text packed 4 characters per element. LEN — the number of characters in ITEXT to be added to the text block. 6STMT — optional, same as in LINE 6 LINED If X = Y = and LEN is positive, the specified text appears in a new line immediately below the previous one. If X = Y = and LEN is negative, ABS(LEN) is the number of characters and the characters are added to the current line. If LEN = 0, a blank line is generated. SEND Completed blocks may be output to the user by a call to SEND. Various options are available regarding what is to be done with the blocks by the PDP-8, and whether or not the blocks are to be reinitialized. The FORTRAN calling sequence is : CALL SEND(IBLK,ICODE) IBLK — denotes the block (s) to be sent IBLK=1 means send the line block IBLK=2 means send the text block IBLK=-1 means send all initialized blocks IBLK=0 has a special meaning which will be discussed later ICODE — an INTEGER*** array with 5 elements. Selects the options to be used for the call. The meanings are as follows : ICODE (1) — 1 = reinitialize (make empty) all specified blocks when done sending = retain blocks after sending ICODE (2) — 1 = replace block (s) sent in the user's PDP-8 data structure = retain current PDP-8 data structure ICODE (3) — 1 = do not display the block (s) = display ICODE (4) — 1 = erase screen before displaying block (s) = add block (s) sent to current screen image ICODE (5) — 1 = put up frame before displaying block (s) = do not put up frame Non -initialized (empty,) blocks are not sent. An option is available which will cause the line block to be sent to the display and re-initialized if it fills up before another SEND call. To use this option, the block must not be marked to replace the current PDP-8 data structure, and must be for display. To do this: IC0DE(2) = IC0DE(3) = SEND (0,1 CODE) calls to LINE and LINED, possibly filling up several line blocks SEND (1,1 CODE) 10 This option behaves as follows : (a) it remains in effect -until the line block is sent explicitly (as by the second SEND call above), (b) if more than one block is sent, only the first will cause an erase or frame , (c) when the line block is finally sent explicitly, the ICODE parameters from the SEND (0,1 CODE) are used (erase and frame behave according to (b), (d) sending the line block explicitly clears the option. Writing an interactive program to draw a circle at a specified location on the screen is now relatively trivial, and the code might look as follows : DIMENSION ICODE(5),IMASK(ll) C C SET IMASK TO ECHO TEXT LINES & ACCEPT J.S. HITS C IN DRAW AREA C DATA IMASK/4*0,1,5*0,1/,FAC/.O1744/ C C SET ICODE TO REINITIALIZE BLOCKS AFTER EACH SEND, C DISPLAY ONLY WITH ERASE AND FRAME C C DATA ICODE/1,0,0,1,1/ CALL MASK (IMASK) 1 CALL MESAGE('TYPE IN RADIUS IN INCHES', 24) CALL NUMBE R ( RAD IU S ,61) IF (RADIUS. GT. 3. ) GO TO 1 CALL MESAGE (' JOYSTICK CENTER', 15) CALL HIT(X,Y,62) INTEN=0 DO 69 1=1,361 SC=X+RADIUS*COS (I*FAC) YC=Y+RADIUS*SIN (I*FAC) CALL LINE(XC,YC,INTEN) 69 INTEN=1 CALL SEND (1, ICODE) GO TO 1 END C C RETURN A NUMBER TYPED FROM THE KEYBOARD C SUBROUTINE NUMBER (XNUM, *) DIMENSION ITEXT(20) COMMON ITEXT CALL REPLY ( IT YPE , LEN , NCHARS ) IF (ITYPE.NE.O) RETURN 1 IFIRST=1 11 ILAST= NCHAR CALL FINDNM( ITEXT, IFIRST,ILAST) IF (IFIRST.EQ.O) RETURN 1 XNUM=NUMCHR (ITEXT , IFIRST , ILAST) RETURN END C C RETURN COORDINATES OF A J.S. HIT C SUBROUTINE HIT(X,Y,*) DIMENSION ITEXT (20) COMMON ITEXT CALL REPLY (ITYPE,LEN, ITEXT) IF (ITYPE.NE.l) RETURN 1 X=ITEXT(1)/124.1 Y=ITEXT(2)/12 4.1 RETURN END 2.3 Extended Input/Output Facilities The standard READ/WRITE statements of FORTRAN IV can also be used. Simply replace the unit designations 5 and 6 with 1 and 2. Then each line produced by a WRITE will be sent to the terminal and each line to be READ will originate as a typed line from the terminal. After every 32 lines sent by WRITE statements, the display screen will be erased and display of subsequent lines will begin at the top. Note, as an example, that dumping 2000 lines of calculations on the screen is obviously not an effective use of this feature. 2.h Creating a Module Using COMMUNE Programs to be run from the graphics terminals using COMMUNE must be link -edited into the graphics load module library. They must also have CALLER, the routine to interface the user's FORTRAN program to COMMUNE, link-edited into the program and specified as the entry point, To do this, the user's deck should be set up as follows: 12 /*ID // EXEC FORT (FORTRAN source deck) /* // EXEC LKED ENTRY CALLER NAME (R) /• is the name "by which the program is to he referred when it is started from the terminal with a !S command (i.e. , !S ). To allow use of the FORTRAN READ/WRITE facility, insert the card INCLUDE SYSL1B(X#FI0CS) before the ENTRY card. 13 ]M0 « lUh - 13T0 - 13^ - SYSTEM LIKE (Screen Sagraen-t 0) Program Segment Line 170 Ikk 120 1^ 50 2k Menu Area (1) Answer Area (2) Return Area (3) Draw Area (*0 Draw Center (l07i,7lU) Prompt Area (5) (7) TIME ^_ Light Button Area Panic Area L61 !§1 SSL— Keyboard Input Line _J l6^ -^ — -1600 ^ ==r - } 2 lines - 136U 32 lines ) 161+ 3 lines 70 2 lines 10 characters 65 characters 10 characters Figure 1. Display Screen Sectioning Detail Ik 3. LIBRARY MAINTENANCE PROGRAM The graphics library maintenance program, LSD, has been developed to provide facilities for storage, retrieval, and manipulation of data structures in the graphics filing system. It allows pictures to be sent from the PDP-8 and saved in the remote computer library or fetched from the remote computer library, and sent to the PDP-8. Pictures can be copied within the remote library; there are provisions for shared access to files among users, and there is also a provision for allowing pictures to be plotted by the hardcopy output package, P0T (c.f. 3.^). 3.1 Invoking and Terminating LSD LSD is started and operated from the PDP-8 remote communications program REACT (c.f. [2]). After the user logs on to the remote computer via REACT, he invokes execution of LSD with the command !S LSD. All lines subsequently typed are interpreted as LSD commands until LSD is terminated with the IHALT command. At that time, all open files are closed and necessary clean up procedures are performed. 3.2 Command Syntax All of LSD's commands are uniquely identified by the first two letters of the command. Therefore, it is only necessary to type these two letters when typing the command. The catalogue function, for example, can be invoked by typing "CATALOG", "CA", or, for that matter, "CAGRXMMP". Most commands require specification of a file name or a library name. DISPLAY, for example, needs to know what picture to display, and CATALOG needs to know which library catalog to display. The syntax for generalized library names and generalized file names is: 15 Examples 1. Picture name — ( ) * A picture name is an alphanumeric string 1 to 6 characters long. 2. Mnemonic name — () A mnemonic name is an alphanumeric string 1 to 6 characters long, followed by a dot, followed by a mnemonic identification number (0-7). Example: RESIST. 2 3. User name — ( < username > ) An alphanumeric string 1 to 8 characters long. k. Library name — ( ) An alphanumeric string 1 to 8 characters long. 5. Generalized library name — () [ [. ]] a. CATALOG b. CATALOG PICLIB c. CATALOG HASKIN. PICLIB The defaults for specifying a library name are as follows i. if the username is omitted, the name used is the one by which the user has logged on (i.e. Ex. b) ii. if the entire library name is omitted, the user- name is chosen as above, and the default library name used is PICLIB (i.e. Ex. a). In the syntax descriptions, brackets. ([]) around an item indicate that it is optional and may be omitted, and braces (.{}) indicate that a choice must be made among the items enclosed. 16 6. Generalized file name-~(< gfilename>) { }[/< libname>] TTinm r»nainp> smnemomcname- Examples d. PLOT RESIST e. PLOT RESIST. f. PLOT RESIST. /PI GLIB g. PLOT RESIST/HASKIN.PICLIB h. COPY RESIST. 2 /PICLIB JUEK.3/JOHTOOE. JUNKLIB As a rule , blanks are used as separators between command fields and, therefore, may not be imbedded in command, file, or library names. Also, when blanks are used to separate command fields, one and only one blank must be used (i.e. PLOT Li JESIST is not valid). 3.3 Commands Saving of Items SA[VE] SAVE allows a picture or mnemonic to be sent from the PDP-8 and saved in the remote library. The procedure for doing this is to first type in the SAVE command, and then, after LSD replies "SAVE READY" type the REACT command "##" to cause the picture to be send to the remote computer. The new picture or mnemonic replaces any previous occurrence in the specified library. Deletion of Items DE[LETE] Deletes the picture or mnemonic instance in the specified remote library. IT Retrieval of Items FE[TCH] Retrieves the specified item and sends it to the PDP-8 where it replaces the current picture in the data structure. LSD then replies with a message to indicate whether or not the item was found . Display of Items DI [SPLAY] The action of DISPLAY is similar to that of FETCH, except that the item is only displayed instead of replacing the current data structure. Copying Items CO[PY] The item specified "by is copied into , anything previously in the second file being overwritten, COPY can be used to transfer files from one user's library to another's library. Obtaining a Catalog CA[TALOG] A catalogue of the items in the specified library are displayed in the menu area on the terminal. Should this list exceed 25 items, the rest may be obtained by typing "MORE". Any other response will exit from catalog mode, allowing another command to be typed. When all names have been displayed, "DONE" will be displayed and another command can be typed. 18 Automatic Local Save Option AU[TO] DA[UTO] These commands turn on and off, respectively, the "automatic save" feature in the PDP-8. When AUTO is in effect and a picture is sent to the PDP-8 via a FETCH command, the picture is saved on the PDP-8's local disk library. DAUTO, which is in effect until an AUTO command is typed, prevents this from occurring. Obtaining Hardcopy Output PL[OT] [