d.ap;.ps 60,70 .title SCI__APL ,.subtitle USER MANUAL  .hl 1 ^&INTRODUCTION\& X  SCI__APL was developed to provide an interactive language for the VAX computer center. This version is based on the work of:  .list L .le ;Rodnay Zaks .. A MICRO PROGRAMMED APL IMPLEMENTATION .. SYBEX 1978  x.le ;Alan Kaniss, Vincent DiChistofaro, John Santini .. An APL Interpreter in Pascal .. BYTE publications 1979 @ .le ;Bill Yerazunis .. A Rensselaer Pollytechnic Institute M.S. thesis ..  l.end list  The APL implementation is meant to be an almost full implementation of 4the langauge with some "improvements" to make it more suitable for the VAX environment. This version is not optimized to be efficient either in memory or in CPU time. ` The following sections are included in this report: ( .list .le ;^&INTRODUCTION\& T .le ;^&APL fundamentals\& .le ;^&FUNCTIONS and FILE access\&  .le ;^&APL goodies\& .le ;^&SCI__APL and normal APL comparison\& .le ;^&TABLES\& H .end list .page t.hl 2 ^&APL help facility\&  < An attempt has been made to provide a general APL help facility. The help file is available from DCL via:  h #####^&$ HELP APL {topic} \&  0 The problem is that DCL does not translate APL characters into the APL character set, and does not know about operator equivalences.  \ A more flexable help procedure is available once the user is in APL. After the user has entered: $ DO APL , or started the $interpriter in some other manor, he can enter the "help" command   #####^&help apl {topic}\& P  The "topic" can be void, to get the list of all topics, or it can be the start of a topic line, the operation symbols, or the |operation mnemonic.  D The page numbers in the help information are the pages in reference 1. Below is a list of some good books on APL.  p.list .le ;^&APL: The Language and Its Usage\& 8  -- Raymond P. Polivka, Sandara Pakin -- Prentice Hill, 1975. .le ;^&APL Users Guide\& d  -- Harry Katzen, Jr. -- Van Nostrand Reinhold Co., 1971. ,.end list  .subtitle APL fundamentals X.page .hl 1 ^&APL fundamentals\&   APL is an interesting langauge in that it provides a compact, though somewhat unreadable, way of writing programs and doing interactive computations. LA limited subset of APL can be learned rather rapidly, but the user should be warned that a full understanding of APL will take time. As skill develops the user can take more xadvantage of the full capability of the language.  @ This section is an attempt to describe a subset of SCI__APL that can be used to get off the ground. It should be noted that this section contains  a number of simplifications that may be generalized in later sections. l The following conventions are used: 4!.list !.le ;{...} represents optional parts of a command. !.le ; represents a carriage return. `".le ;The commands are given in ANSII mode, as discribed below. If the user "has access to an APL terminal, then, in general the position of the letters (#is the same, with the left quote, `, representing the backspace. #.end list # T$.hl 2 START-UP, SAVE and LOAD, SIGN-OFF $ % Begin to use the SCI__APL system the user should LOGON to the VAX, and %then enter: % H& #####^&$ DO APL \& & ' The APL system will be loaded with a clear work-space and prompt t'the user by outputting 8 spaces and leaving the cursor there for input. ' <( To LOAD an already saved work-space, the user should enter: ( ) #####^&)load {work__space__name} \& h) ) The work__space contains the complete values of variables and functions 0*that were SAVED. If a work__space__name is given, then the "active" *work__space__name is so set, and this file is loaded. This "active" *work__space__name will be used as the default, until re-set for \+any future LOADs and SAVEs. + $, After some work has been done, the user can save the current state by ,entering: , P- #####^&)save {work__space__name} \& - . Finally the user can exit from the APL system by entering: |. . #####^&)bye \& D/ / There are two character set modes that can be used, depending on the 0terminal. The first, and default, is the ANSII mode. In this mode, almost all p0APL operations are given by their "position" on the keyboard. This 0to use this mode use the )help file or a crib sheet of where the "proper" 81apl characters are on the keyboard. In addition to the 1single, or overstruck commands, the user can always use the 2mnemonic commands. These are also given in the )help file. d2The exceptions to the "position" constant ANSII commands are as follows: 2 ,3.list 3.le ; = .. for assignment. 3.le ; X .. for multiply. X4.le ; % .. for divide. 4.le ; * .. for power. 5.le ; ? .. for roll. 5.le ; " .. for the comment double quote. 5.le ; | .. for the equal compare. L6.le ; ~ .. for the non equal compare. 6.le ; A .. for and 7.le ; V .. for or x7.end list 7 @8 To enter the true APL character mode, enter the command: 8 9 \&)APL \& l9 9 Once this is done the APL characters will be treated properly so that 4:the system will accept them. At this time the user should switch his terminal :to the APL mode if not already there, or some of :the displayed characters will be `;quite strange. This mode switch is given in a subsequent TABLE. ; the user can switch back to the normal ( command. < <.hl 2 INTERACTIVE MODE T= = APL is originally in the interactive mode, i.e. each statement is >executed immediatly. This mode is generally useful for "desk calculator" >type operations, and for initalization. > H? A statement consists of expressions, e.g. 2+3, and assignments, ?e.g. x = ... . If the statement is an expression, then the result is shown @immediatly, whereas if the statement is an assignment, then the result is t@stored. note.. any assignment can be used as a value for a further expression, @and an assignment can be turned into an expression by preceeding it with a + \& _ ` to obtain information about the APL system or about a topic, such |`as an operation. It should be noted, however that the DCL system does not `properly convert all characters, and thus to get the formats of the commands Dain APL mode, one must first enter APL before giving the )help command. a b Two more features of SCI__APL should be mentioned at this time: pb b.list 8c c.le ;In order to provide for dthe number of operators available, many of the operators act somewhat dddifferently depenting on whether they are MONADIC, i.e. have one operand, dor DYADIC i.e. have two operands. for example: ,e e a X b ### means "a" times "b", where as: X c ##### means the sign eof "c", i.e. +1 if "c" is greater than 0, 0 if "c" is zero, and -1 if "c" Xfis less than zero. f g Thus is is essentual that the user be sensitive to this difference gso that the proper operation is performed. g Lh.le ;In order to permit the SCI__APL to be used on standard terminals, the hcharacters used for many of the operators are just upper case alphas. These iwere chosen to usually be in the same place on the keyboard as the standard xiAPL operator, and thus may at times not be too meaningful. iThese are shown in the TABLEs on @jAPL operations. j k.end list lk k.page 4l.hl 2 VECTOR -- ARRAY operations. l l As was stated APL provides for automatic VECTOR and ARRAY operations. `mThe first question is how to generate vectors and arrays. This is done, mat least conceptualy in two phases, and of course since this is APL, from (nright to left. The first phase is to determine the VALUES that go into nthe structure, and the next phase is to determine the SHAPE of the structure. n To The simplest way to set values is to enter them, thus, for example othe vector consisting of 10, 20, 30 can be stored into x via: p p #####^&x = 10 20 30\& p Hq To concatinate two vectors just use the comma, conatination operator qbetween them. For example, r tr #####^&x,x\& r If there is no begin__condition, then the same action is taken as if there were a true condition. Q  The curly bracket "}" is the ENDing of the loop block. This is also optionally followed by a end__condition. }If the condition is TRUE, then control passes back to the start of the block, and if the condition is FALSE, Eor non-existant, then control continues to the next line.   The body of a loop can contain all the standard set of APL statements. qIn addition there are the statements to re-cycle the loop, i.e. the NEXT, "N", statement, and to exit the loop, i.e. the 9BREAK, "B", statement. Both of these are followed by a condition that determines whether the action is taken.  e This control structure has a number of flavors, depending on how it is used. The following gives some of these: - .lit  Y FORTRAN SCI -- APL  ------- ---------- !  IF( condition ) THEN { condition  M statements statements   ENDIF } y  --------- --------- A  DO nnn I = 1,20 i = 1 m { 5! statements statements ! !nnn CONTINUE } (i = i+1) .lt 20 a" ".end literal )# # this last line of the APL program introduces two new concepts. #1) the assignement i=i+1, being enclosed in (...), is executed first, U$and has a resulting value, i.e. the new value of "i". $2) the .lt 20 is the first example of an APL logical operation. The complete %set of operations is supported, i.e. _.eq, _.ne, _.gt, _.ge, %_.lt, and, _.le . % I& In-side of a loop structure one can put BREAKs and NEXTs &A BREAK, "B", will skip the rest of the loop, 'including the end "}" line, and u'then continue with the next statement after the "}" line. A NEXT, "N" 'will also skip the inside of the loop, but will then resume processing =(with the "}" line. This means that the loop may then be re-cycled. (An example of these control structures is given below: ) i).lit ).tp 10 1* * FORTRAN SCI -- APL * ------- ---------- ]+ + DO nnn i=20,1,-1 i = 20 %, , { , Q- statements statements - . IF( b(i) .NE. 17 ) GOTO mmm B b[i] .ne 17 }. . statements statements E/ / IF( a(i) .NE. 3 ) THEN N a[i] .eq 3 0 q0 statements statements 0 91 ENDIF 1 2nnn CONTINUE } i=i-1 e2 2mmm CONTINUE -3 3.end literal 3 Y4.hl 2 FUNCTION editing 4 !5 An sos type editor has been developed to create, read, write, and 5edit functions. This is used by entering: 5 M6 6 ######^&)sos {function__header} \& 7 y7 ################# or 7 A8 ######^&)sos <{=}file__name \& 8 9 If a function header is given, then the named function, if it exists, m9is moved from the work space to the editor. 9If the function does not exist, then 5:the command line is moved to the editor as the :start of the function. If no name :is given, then the editor is started with no data in it. a; ; If a file name is given, as denoted by the "<", ) > Once the APL editor is loaded, >the lines can be edited by the user. The I?commands were designed to be similar to the standard SOS commands, ?except that the line numbers are not sticky, i.e. will change as lines @are inserted and deleted. u@The commands are fully discussed in the TABLE on editing, these are as follows: @ =A.lit Aa{lter}{range} d{elete}{range} e{xit} e{xit and }q{uit} Bi{nsert}{range} m{essage}. p{rint}{range} iBr{eplace}{range} <{=}read__file__name >write__file__name B.end literal 1C C C The edit commands are one character long, lower case, and immediatly ]Dfollowed by the range. The range is ".", nnn, nnn:mmm, and in the Dcase of print "/", "/.". The a{lter}, i{nsert}, and r{eplace} are generally %Eterminated by a blank line, or a p{rint} command. E E The a{lter} command shows the line to be altered, QFand then accepts alter lines from the Fuser. These alter lines are of the following form: G }G #####^&{spaces}{d's}{spaces}{i{inserted.text} \& G EH The alter process is to insert the new text Hwhich follows the first "i", just before Ithe character under which the "i" falls, qIand then to delete the characters above Ithe string of "d's". note.. only one string of d's is permitted 9Jper alter line. After Jmaking the alteration, changed line is shown again, and the user can make Khis next alteration. He finishes his alteration by entering a carriage eKreturn, or a p{rint} command. K -L At any time the edit buffer can be written to an external file with the L">" command, or overwritten by reading from an external file Lby the "<" command. YM M The buffer can be written to the help file by the "m." command. This !Ncan be used to note errors in the system, etc. N N To exit from the editor use the e{xit} command. The e{xit}q{uit} command MOis also available to exit if the user has just been creating a message, or if Othings have gone wrong enough that he wants a fresh start. P yP.hl 2 ^&FILE access\& P AQ There are a number of different files that can be accessed within the QAPL system. These are generally divided into the following three types. R mR.list R 5S.le ;WORK FILES .. These contain the state of the APL interpriter at the Stime the user executed a ")save" command to the file and restore this state Swhen he enters a ")load" command. aT T.le ;FUNCTION FILES .. These contain test data that is read in written thru )Uthe psudo-sos editor. The data within these files contains the definition of Uone APL function. U UV.le ;DATA FILES .. These contain data that can be read and written by the Vexecuting APL program. The types of files supported are: BINARY and CHARACTER. W W.end list W IX The following sections discuss the access and formats of each of these Xfiles. Y uY.hl 2 WORK FILES Y =Z A work file consists of the entire set of function and data definitions Zactive when the user SAVED his work space. The commands that are related to [the work files are: i[ [ #####^&)wsid {new_name} \& 1\ \ When the user enters the system, the work file name is initalized to \apl.ws. At any point the name can be shown, and optionally changed via ]]the preceeding command. note.. the )save and )load commands may also change ]the name of the work file. %^ ^ #####^&)save {new_name} \& ^ Q_ At any point the user can save the current state, either over the _current work file, or onto another work file by entering the )save command. ` }` #####^&)clear \& ` Ea To remove all function and variable definitions the user can enter the a)clear command. This will reset all the internal variables to their LOGIN bvalues. qb b #####^&)load {new_name} \& 9c c To reload the variables and functions that were previously saved, the duser can enter this command. It should be noted that this command does not eddo an automatic clear so that any variables and functions that are not in the dsaved work file are not altered. -e e.hl 2 FUNCTION FILES e Yf Function files contain the definition of APL functions. These files fare standard ANSII files, and thus can be created and edited outside of the !gAPL system, and then read by APL. The access, within APL, gto these files is thru the psudo-sos editor. Much of this was discussed in gthe previous section. The commands to access these files are as follows: Mh h #####^&)SOS <{=}file__name \& i yi This results in reading the text file "file_name" into the sos buffer, iand Ajentering the editor. The "=" is used to point to the sci__apl library that jwill contain useful functions. Once the user is within the editor he can kread an write files via the following commands. mk k #####^&<{=}file__name \& 5l l This results is CLEARING out the edit buffer, and reading in the ltest file "file__name". am m #####^&>file__name \& )n n This results in writing out the edit buffer to the text file n"file__name". Uo o To load the data in the edit buffer into the APL work space, the puser must e{xit} from the editor as follows: p p #####^&e \& Iq q.hl 2:DATA FILES r ur Data files are read and written from within APL by using the "L" rconstruct, or implicitly if unit 0 is open. =s s The user must first open an input or output file via the command: t it #####^&)unit {number {access{type {file__name}}}} \& t 1u Unit numbers range from 0 thru 9, where 0 is the unit assigned to uthe standard APL input and output. Accesses consist of either R for read, uor W for write, The type consists of B for binary or C for character. ]vThe file name is optional and is defaulted to the name aplfile."t""u", where v"u" is the unit of the file, and "t" is the type of the file. %w w If no number is given, then a list of the open files is shown. If wno type is given, then the file specified is closed. If no name is given, then Qxthe default name is supplied. x y The program normally reads from a file, unit number nnn, by using the }yL[nnn] as an expression, and writes to the file by using L[nnn] as the target yof an assignment. In addition, if unit 0 is open, then the normal CRT output Ezwill also be copied to that unit. and the normal CRT input will be read from zthat file until an end of file. { q{.hl 1 ^&SCI__APL and standard APL comparison\& { 9| (to be done) |