RPD System I

An Integrated Development Support Environment for Robot Programming (RPD System) : System Manual September 16th, 1983 Ogan Gurel IBM Thomas J. Watson Research Center Yorktown Heights, NYIBM INTERNAL USE ONLY - DRAFT ** DO NOT Copy #* ii RPD: System ManualIBM INTERNAL USE ONLY - DRAFT # DO NOT Copy x PREFACE ming neeeTated Development Support Environment for Robot Program- maneakPD = Robot Program Development) is s severe intended to aid tag facturing engineers and robotics researchone designing, cod- seoegitins, testing, and debugging robot proceace across a number tafaceee eroezanming languages. The system ie eet AML (A Ma~ suigetuxing Lenguage) with the Gold Filling 11 enhancements running on the IBM Series/1 controller for the IBM $8/1 Rete System. plementation manual also discusses how tree expandability and ex- jensibility ts achieved and how futere enhancements and ‘improvements to the system can be effectuared: Supporting Documentation: The reader of this document is assumed oy Rave 2 basic knowledge of AML and the TBM RS/1 Robot System. ‘The following publications should be referced tr whenever necessar; A Manufacturing Language Concepts and User's Guide, 08006, and ~ orang Language Concepts and User's Guide A Manufacturing Language Referen and Screen Editor, 08007 Preface iii'BM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #** iv RPD: System ManualNwwat 1BM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* CONTENTS INTRODUCTION «2... eee, ial System Structure 2... eel Command Forms 6 eee What this document is about...) |, en 3 LINE COMMAND PROCESSING AND THE SYSTEM KERNEL 5 Introduction poOebHoGodsubouue ee 5 Design Criteria... || ea oreo ae ea The Basic System Loop epee areata! ‘The Command Read Cycle - READCMD |] ) | | a Processing the input line -- PREPROG| | | | |.) | ee) Command Execution File Correspondence =~ PROCCMD | |||” 45 COMMAND EXECUTION AND THE DOMAIN ENVIRONMENT 19 Introduetion eGeoponodeoudoue eee 19 A sample command and its execution cycle ee eo) The full-screen domain environment -- Introduction... 21 Preparing the screen display ...........,. oe 22 Displaying the editing object and performing commands | | 27 DESIGN/AML, MACRO DEFINITION AND MACRO ECUTION .... eee cee fee 85 Introduction... TTI Il 3g DESIGN/AML =e wee ee lll OS Some possible implementation schemes | || | | ee s7) Macro interpretation and execution... eee 40 IMMEDIATE COMMANDS AND PF KEY COMMANDS... 49 Introduction ee eee ee 4a) Immediate Commands 2. | pee A Inmediate Command Interpretation in READCMD aoe st PR key commands se 54 Programming the PFkeys .. lt gy -O FULL-SCREEN COMMAND PROCESSING AND TEXT ANIPULATION ....,.......0.- ee el 1 Introduction 2 iii itt 61 2 The full-screen command loop .. 2. 11) 1 lI 61 3 Reading the present line -- READLINE Be ical 4 Interpreting prefix commands -- PFXPROC |) 1) )]) 67 5 The DELETE (D) prefix command ...... 1.2). ore70 6 Full-screen text manipulation |). |) | eee iaa72 7 Some more full-screen prefix commands 1... 1 1... | 75 8 Scrolling in the full-screen mode... 1... 1...) «(37 0 PENDANT COMMANDS AND TEACH MODE ........ 81 1 Introduction 2... Be eel 2 The Pendant Interface for the AMLEE system |). ||) gy 3 Pendant Key Command Interpretation .... 1... . 2. )~ 2 Contents vvi nak 'BM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* Pendant Key Execution 6... 2, ‘TEACH MOI Future Pendant Key command applications RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** 1.0 INTRODUCTION 1.1 SYSTEM STRUCTURE The Robot Program Development System is structured in the form of Domains each of which constitute a related set of robot program de~ Yelopment tools that aid a robot programmer in designing, coding, editing, testing, and debugging robot programs. Typical examples of domains and their uses can be illustrated as follows: editor This domain typically allows the programmer to create and edit his program in the form of text. assembler Here an assembly language program is assembled into its corresponding machine language object code. In the Robot Program Development System we will not be so concerned with assemblers. debugger Using a debugger a progranmor can observe and control the execution of his program. In addition, the programmer may also be able to observe relevant aspects of the na~ chine while the program is actually executing The Robot Program Development system uses the domain structure in two ways: It forms a horizontal structure of different progranming domains within the context of a single robot programming language and it forms a vertical hierarchical structure of different programming domains within different robot programming languages. In other words, the system is designed to support a number of robot Programming languages, each dealing with a different level of ap~ proach to the implementation of robot applications Thus, each robot language can have its own basic program editor which is customized to the specific demands of programming in that Particular language. An example would be a pendant editing teach mode function that would work well for low-level robot languages while another editor for a more high-level robot language may supply @ number of knowledge-based or artificial intelligence-based pro~ gram development tools, as well. It is intended that there be a great deal of dynamic interaction between domains encompassing different programming languages in addition to the natural interactions between domains that operate within the context of a particular language. Such a hierarchical interaction would facilitate both the fine-tuning of applications Programs written in a high-level robot progranming language, as INTRODUCTION 1'BM INTERNAL USE ONLY - DRAFT * DO NOT COPY # wea ns the more refined development of those high-level robot progranming languages according to the information gleaned from studying the low-level correlates of such high-level robot programs ming languages qo facilitate the communication between domains, a simple but pow erful structure underlying the software database that is involved throughout the development process has been proposed. This sores Ware database assumes a deterministic model of domains in that the scaging mule is considered when designing the various programming domains. ach domain takes as input to the processes that It dese number of files specified by the user. These files may be both abe Stract files which are generated by the user or derived files which eseherated by domains in the system. The process of presenting a file as input to a domain is called attaching a file, and the file So input is called an attached file. Furthermore, although each dow main may take any number of files as input, each domain may, ia itself, generate one and only one file (from the point of view of fhe user) from any processes that operate on the attached files, This generated file is also an attached file which is associated with that donain's Filegroup The filegroup associated with a domain is fhe set of all files that have been generated by that domain. This implies that generally, those files are all of a pareiealar fype and have @ specified format that is significant to the oper ations of that domain. Mich in turn are structured into filegroups which correspond very greatly with the domain structure of the system. The whole idea be. Bind the system then, is that one uses these domains (as related Sets of development tools) to systematically refine and develop the software database as a whole, 1.2 COMMAND FORMS For ‘robot programming the Robot Program Development System uses a rneer Of different kinds of domains, cach of which can be used by fhe robot programmer in differing contexts. Furthermore, the aus. Pex and types of domains presently supported by the Robot Program Development System will be necessarily different from the kinds of donains supported in future versions of the Robot Program Develop= ont System. Although our domains may be very different and may, ia fact, be undetermined, one thing is for sure: the way the system views the tools supported by a particular domain. More specifically, each tool in the set of tools that defines the domain can be ascribed to a command that can be interpreted and exe. cuted by the system. The conmand may be as sinple as instructing 2 RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* the editor to go to the top of the document or as complicated as felling the robot to define @ new point in the workspace using dy- ganic sensing and guarded motions. In the Robot Program Development System there are seven basic command forms that are processed in cc. Sentially the same fashion throughout each domain, future and pres ent. These seven forms are listed below: line cmd This is the basic command form pro immed cmds An immediate command is also processed by the system kernel, but it is interpreted without any further Processing macro cmd This command is a macro which is defined by the user in the MACRO-AML language. Macros are processed by the system kernel. the system kernel Prefix cmds These commands are interpreted by the full-screen command processor and allows commands to be interpreted in a full-screen context metacmd Meta commands handle context switching between domains, multitasking of domains, and the interact ion between donains and filegroups. Essentially. mete conmands enable the integration of large nunbere of domains and robot languages with an equally large software database operated on by those domains PF cmd PF commands are invoked through pressing the appro- Priate Program Function Key. Although the process ing Of these conmands may be different, the actual intere pretation of the PF commands, in most cases, is the Same as the interpretation of the standard line,macro, or meta commands. PF keys can be pros grammed through line or macro commands. Pendant cmd Pendant comands are invoked by pressing the appro- Priate keys on the pendant (or poc) box. In this way, Specialized commands that require interactive teaching of the robot can be processed and interpreted. Oftentimes, however, the pendant interface provides for commands that provide other useful functions be~ yond robot teaching, as well. 1.3 WHAT THIS DOCUMENT IS ABOUT This document is a combination user's guide and implementation man wal to the Integrated Development Support Environment for Robot INTRODUCTION 3,IBM INTERNAL USE ONLY - DRAFT ** DO NOT Copy #* Programming. The decision to combine these two particular docu ments into one is basically why this document has been called a Sys- fem Manual. It is has been written so that a user can get on the system and do some basic tasks as well as a person interested in the implementation can garner much detail about the inner workings of the system. The basic approach to the implementation manual takes the form of a tutorial in the detailed ideas that formulate the implementation of Talor portions of the system. Instead of describing every single jine of code that was written, it was felt that this approach woold be more beneficial both for the person interested simply in the techniques behind the implementation and for the person interested in continuing work on some aspects of the system. As such, the reader of this document should be warned that reading the individual chapters out of order may result in serious confusion. This is par= ticularly important when reading the chapters devoted to the implementation of the system as the discussion is developed with the assumption that we are starting from scratch. 4 — RPD: System ManualIBM INTERNAL USE ONLY - DRAFT * DO NOT COPY #* 2.0 LINE COMMAND PROCESSING AND THE SYSTEM KERNEL 2.1 INTRODUCTION Line commands are the most important and versatile form of user interaction with the system. The concept of a line command in this system implies 1) the command is entered as text through the keyboard (and not through any buttons or other form of user input) 2) line conmands may be entered only when the cursor is posi- tioned on a specific line on the screen and text entered on that line may only be interpreted as a line command. note: if the system is ready to receive commands, then the cursor is at the position indicated by the domain prompt In this chapter we will discuss how this scheme is carried out as well as the important design considerations that went into the specific implementation details of line commands. The discussion will describe, through narrative, the author's development of ideas and code regarding line commands. Therefore, any AML coding examples will be fragments of the actual corresponding code in the real sys~ tem, However, any inconsistencies from the real code will be noted im the text. In other words most of the coding examples will simply be extracts from the larger whole which in the end result will be discussed in its entirety. 2.2 DESIGN CRITERIA 1) Generalized Command Processor 2) Must fit in small memory <52K 3) Commands must be able to support arguments or operands 4) The conmand processor must be able to support a virtually unlimited set of line commands 5) the command processor must be capable of easily switching between domains (i.e. different command sets). LINE COMMAND PROCESSING AND THE SYSTEM KERNEL 5'BM INTERNAL USE ONLY - DRAFT ** DO NOT Copy ##* 2.3 THE BASIC SYSTEM LOOP The following subroutine which is loaded as part of the system ker pel is the heart of the system. It is the one that is always running in the system and the loop that can be seen in the 2nd and 3rd lines of the subroutine is the one that actually performs the processing of all commands, although different commands may be processed and interpreted in different ways. START: SUBR; LOAD('SYSIPL'); LOOP: PREPROG(READCHD) ; BRANCH (LOOP) ; END; When the system kernel is loaded, the subroutines PREPROC and READCMD come with it as well as the subroutine START and various other routines. Therefore after IPL'ing the SERIES/1, one most first load the system kernel through the following AML statement: LOAD(' SYSKER') 5 But to actually, run the system one invokes the subroutine START, by entering the following AML statement: (appropriately enough) START; 4s one can see the first statement in START is LOAD('SYSIPL') which, gf course, has no relation the the IPL process for the SERIES/1. Incidentally, IPL is IBM lingo for "get ready and initialize"; some what akin to the process of putting a quarter into a waiting video game. This load statement reads in AML statements froma file called SYSIPL which in particular ways initializes critical parts of the system. However, at this point we don't know what the system looks like so we'll leave this file empty; the system can thus be considered a tabula rasa, excepting of course the three subroutines We loaded with the file SYSKER (namely START, PREPROC, and PROCCMD). When we start learning more about the system later, we will begin to build our SYSIPL file and make things more complicated 4s we said, the most important part of the system was the loop in the second and third statements of START. According to our defi~ nitions of what a line command is the system must somchow read a command or perhaps, more accurately, allow the user to force it to yead 2 conmand from a particular line on the screen. This seems to be the job of the subroutine READCMD which then passes the command that somehow was read as an argument to the subroutine PREPROG which, we are assured, will somehow process that command. After that's finished we then continue to the third statement which then compels the system to BRANCH back and repeat the whole cycle again. Let us now examine in more detail what this loop does: 6 — RPD: System Manual'BM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* 2.4 THE COMMAND READ CYCLE - READCMD The task at hand now is to generate a facility for the input of com mands to the system. The following subroutine does this ina sims plified manner for line commands: READCMD: SUBR; REPEAT BEGIN POINT(O, 22); => line 22 is the input Line DISPLAY (DOMTOKEN, |'>'); -- display domain prompt END ONTIL LENGTH (READ(, INLINE)); > read the input line, if ~~ no input then repeat RETURN(INLINE) 5 s> return the new input Line END; -+ to PREPROC Here we have two variables which have not been defined; namely DOM- TOKEN ‘and INLINE. DOMTOKEN is a single character that briefly iden tifies what domain we operating in, and INLINE is a 72 character string that holds the user input. It is evident that INLINE and DOMTOKEN must be defined in the SYSIPL file as follows: DOMTOKEN: NEW STRING(1); INLINE: NEW STRING(72); Note: the author has determined that INLINE should in fact be initialized in READCMD as a local variable as follows INLINE: STATIC STRING(72); (-- this code is not reflected in the actual code for READCMD) ‘pew Problem that arises is how a domain is booted into the system (ebvious ly DOMTOKEN must now be set to some character reflecting the current domain context). How does the system kernel know what doe weer at 18 Mow operating in? (Note: we can not be in the system loop without entering a domain because the current domain context deter. mines how the commands are to be interpreted -- the system kernel cnly processes the commands and provides the user interface.) We must, in this case make a modification to the START subroutine which runs the system. This modification will load an IPL file that docs for a domain what the SYSIPL file does for the system as a whole. Since this new domain IPL file initializes such values as DOMTOKEN, it must be loaded after the SYSIPL file is loaded. ‘Thus START wild look as follows: START: SUBR; LOAD('SYSIPL'); LINE COMMAND PROCESSING AND THE SYSTEM KERNEL 7IBM INTERNAL USE ONLY - DRAFT ** DO NOT Copy #* LOAD(DOMAIN| 'IPL'); == domain IPL file LOOP: PREPROG(READCND) ; BRANCH (LOOP) ; END; Obviously then, we also have to describe the variable DOMAIN, which is a long-form version of the domain identifier. In particular $f the current domain is the CON then their is a corresponding IPL file for the CON domain called CONIPL, the name of which is derived by concatenating the domain identifier DOMAIN with the string 'IPL' as in line 2 of the START subroutine. This means that DOMAIN must be defined AND initialized for the first time in the SYSIPL file; we could just as well define it in the domain IPL file, but that would defeat the purpose of the DOMAIN identifier. Thus we have a routine in SYSIPL that asks the user for the first domain to operate in (en= ter into) and sets DOMAIN appropriately. This gives us ‘the flexibility of allowing DOMAIN to be redefined and thus creating a new environment by loading in a new DOMAIN IPL file. For purposos Of discussion let us assume that this routine exists and has initialized DOMAIN to 'CON' as follows DOMAIN: NEW STRING(5) Is 'CON'; The domain IPL file for the CON domain will now look as follows: DOMTOKEN = 'c'; So let us review now, what we have created: 1) We have a subroutine START that performs the main loop of the system, interpreting commands successively. 2) The entire system is initialized (after loading the system kernel) by the SYSIPL file which among other things, boots the first domain to be operated on. 3) Each domain is initialized (and the domain environment created) whenever the corresponding Domain IPL file is loaded. Eventually this IPL file will load information that determines what commands are to be interpreted and how. 4) We have a simple user interface that prompts the user, accepts a line of input and passes that input to PREPROC (which we don't know about yet) for further processing. 8 — RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT Copy * 2.5 PROCESSING THE INPUT LINE -- PREPROC The input line just accepted by READCMD is simply a string of 72 characters and nothing more (at least not until PREPROC gets through witb 22; Presumably, this input Line represents a conmand with en associated arguments or operands (to be called arguments from aan on) that the user wishes to be processed and executed. Nove exactly the user wishes it to be executed but the system just the sane will insist on processing it. Therefore PREPROC is charged with four responsibilities which it must Perform for each input line it receives from READOMD. Those responsibilities or tasks are outlined below: 1) Separate the actual command from its list of arguments 2) Determine if the conmand is a valid one for that domain 3) if the command is deemed invalid then abort the Processing of that input line and inform the user thereof 4) if the conmand is valid then execute that command Pet US now look more closely at what each of these tasks involve as far as a detailed implementation goes: phe syntax of the command language as described in the Robot Program Development System User's Guide requires at least one blank space Petween the actual command and its corresponding argument’ ieee” This means, of course, that the arguments to a particular command gan be entered on the same input line as the command itself, ‘Then’ fore PREPROC must look for the first blank in the line and use thee aneuent fields respectively. However, we must make allowance for any leading blanks that the user may enter in the input line chick must not be counted as delimiters between commands and arguments, Once the command has been determined (without any enbedded, leading $3 railing blanks) it is then compared with a list of commands vale Doane, UrEeMt domain. This list is held within the varisele PENS which is an aggregate of character strings. Thus the doncig pbk file must somehow initialize this aggregate which it doe by deading another file that contains the definition of DOMGHDS. "The seijements in GONIPL that do this for the CON domain look as follows: UNLOAD ('DONCMDS' ) 5 expunge the previous domain's => command list LOAD(*CONCMDS' ) ; >> load the file native to the CON -> domain that redefines DOMCMDS LINE COMMAND PROCESSING AND THE SYSTEM KERNEL 9'BM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** The file CONCHDS in its present form looks as follows (an indication of the extent of the present command set: 10 RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** DoNcMDs rb » 'FULEDIT' stEXIT! » TOP" > "BOTTOM" »'BoT! » "REFRESH >s'PFI »'PF2" s'PES! s'PF4" » TINSERT" TINS" vant > ‘DELETE" »'DEL! >'DEt » "RENUM' s'up" » "DOWN! > 'NEXT! »‘LIst! uo > "SPEED! > "ACCEL" » ‘DECEL" > "SETTLE" > "SKIP »'Do" > "UNDO" > "REPEAT" > "RUN" > "GOAL" >'Pos' » "REPLACE" FIND! a aus » "ADVANCE" » 'STARTUP" >" SHUTDOWN’ > "SHUTDOW" » "SHUTDWN' > "GRIPPER" s'GET" » ‘PRINT! > 'CREATE" > "SAVE" > "TRACE" »'Mse" s "CONEDIT’ LINE COMMAND PROCESSING AND THE SYSTEM KERNEL, 1IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY * »'EX' » "COMMAND" »'CAPPEND' Gq" » PREFIX" s'cp" » 'CDELETE" s‘cr" > ‘CINSERT’ »'cLt » {CLOCATE" top »'OFIRST" »'CLA" »CLAST' roRt » 'CREPLACE" > "DUP" » "DUPLICATE" "JOIN' 12 RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY # The Xeason the first entry is composed of stars will become apparent jater. In addition it appears that one can have synonyms for the Same command such as IN and INS for INSERT The process of determining the validity of a command is thus reduced to the problem of searching the DOMCMDS aggregate for a match to the command that was just input. sere towever, the command is invalid then PREPROC must abort its op- gration and so inform the user of the error. This is done through a generalized message passing routine called MSGOUT that is part of the systen Kernel. A1l messages from the system, whether they are messages from the system kernel (as in the case of a command error qi othe Amput line), messages from individual conmands, or messages from other parts of the system are passed through this routine ed output onto lines 19 and 20 of the screen. MSGOUT looks as follows: NSGOUT: SUBR(MSG1 DEFAULT STRING(70), MSG2 DEFAULT STRING(70)); POINT(0, 19); DISPLAY (STRING(4) IS DOMAIN] STRING(4),"=> ',MSG1,E0L, ' ",MSG2,EOL,APPLY("|',79 OF '='}); END; Essentially, MSGOUT displays 3 lines 1) this is the first line of the message which is tacked onto a message prompt indicated the domain from which the message was generated. In the case of the CON domain the prompt would look like this: CON => 2) the second line of the message is displayed right below the first line. 3) @ continuous line of hyphen characters is displayed in order to differentiate the message field of the screen from the command input line (line 22) Finally, if the command is valid, we should then execute the command. In point of fact, however, the execution of the command is Processed by another routine called appropriately PROCCMD which loads a file which performs the actual execution of the command. Since the code that really executes each command is resident on disk, we can have a virtually unlimited set of commands without wor. tying about the amount of machiné storage we have left. Adding new commands is about as easy as putting the command name in the DONCMDS conmand directory and creating a new file to execute that command. But it is still not clear how the system knows what file to load and how to execute that file. All that is done in PROCCMD which is the LINE COMMAND PROCESSING AND THE SYSTEM KERNEL 13'BM INTERNAL USE ONLY - DRAFT ** DO NOT Copy #* subject of the next chapter. For now, let us consolidate what we Row know PREPROG does into an AML coding example. This example, however, approximates but is not really a fragment of the actual PREPROC code in the system. It has been modified for documentation Purposes as well as to temporarily eliminate some of the other things that PREPROC does that will be discussed later. PREPROC: SUBR(CMDLINE) ; TEMPLINE: NEW LBLANK(CMDLINE|' ') BPOS: NEW LOCSTR(" ', TEMPLINE) ; CMD: NEW SUBSTR(TEMPLINE,1,BPOS-1) ; ARGLIST: NEW ‘SUBSTR (TEMPLINE , BPOS+1, LENGTH (TEMPLINE)-BPOS) ; IF CMD EQ <'',' '> THEN BRANCH(LOOP) ; IF MEMBER (CMD ,DOMCMDS ) ‘THEN PROCCMD ELSE BEGIN MSGOUT(' INVALID COMMAND’ , BRANCH (LOOP) ; END; "EMPLINE) ; END; This routine (which, as mentioned, is an abbreviated version of the Teal PREPROC subroutine) does essentially the four tasks that we re. quired that it do. The first line takes the input line as received from READCMD and removes all leading blanks from it using a utility Subroutine called LBLANK. This subroutine is part of a file of utility subroutines that is also loaded into the system by the following statement in SYSIPL: LOAD ("UTILITY") 5 This loads the following utilities which are described in more de- TAKE 7 takes a specified # of chars from a string PARSE =~ splits up a string delimited by a certain char INDEX -- finds multiple indices of a string DROP = drops a specified # of chars from a string EXPAND =~ splits up a string into an aggregate RBLANK =~ removes all redundant blanks in a string MEMBER -~ finds a string in an aggregate of strings LBLANK —-- removes all leading blanks in a string The next statement finds that critical first blank that we spoke of before allowing the next two statements to create two strings CMD and ARGLIST representing the command field and the argument field Tespectively. If the command field is empty, then we abort processing and return to the loop. If not then we check to see if the command is a member of DOMOMDS (the command directory for the current domain). To do this we use the utility MEMBER which returns the index of a string within an aggregate of strings, in this case the string is CMD and the aggregate of strings is DOMCMDS and we went to 14 -RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT Copy #* Search for a match between CMD and any string in DOMCMDS. If a match is made then we do PROCCMD which we as yet do not know about. Otherwise we output an error message using MSGOUT (the general sys fem message passing routine) and branch back to the system loop, allowing the user to either correct the command or enter new commands. As of now, what can be say the system does: 1) It IPL's the system kernel and a domain allowing the user to enter commands through the READCND input Line. 2) We have established in a small way, what the domain environment looks like in terms of the commands that can be recognized by that domain. This is implemented through a command directory called DOMCMDS which is redefined for each domain during the IPL' ing of the domain. 3) We have a routine that can process this input line by extracting the conmand from the input line, determining if that conmand is valid and if so passing execution to another routine PROCCHD that executes that command 4) We have a general message passing routine as Well as some utility functions that we loaded using SYSIPL. 2.6 COMMAND EXECUTION FILE CORRESPONDENCE -- PROCCMD As we discussed PREPROC can be considered to be a preparatory subroutine for the execution of commands. If we, indeed, have determined the validity of a command then we are ready to interpret it and as we vaguely hinted to earlier that execution involves loading an execution file corresponding to each command. First of all, what are the characteristics of that execution file? The execution file is basically a file that contains one AML subroutine that does the things specified by the corresponding command in the Robot Program Development System User's Guide. When that subroutine is run, it executes the command using the information in the ARGLIST string generated in PREPROC regarding the arguments to the conmand, Hence when the subroutine is erased from storage or "un- loaded" it frees up the machine storage for more commands as they are entered by the user. ifence only one command is resident in sto~ rage at any one time and there is little pressure on the precious 50 or so K of memory that we have on the Series/1 LINE COMMAND PROCESSING AND THE SYSTEM KERNEL 15IBM INTERNAL USE ONLY - DRAFT * DO NOT Copy #* Another thing to consider is the scheme by which PROCCMD knows what file to load in for what command. In the same vent as DOMCNDS (the domain command directory) there is a similar (in fact very much sim. ilar) aggregate of strings called DOMFILES which is a compendium of all the execution files for all the commands recognized by the domain eres: in fact, a one to one correspondence between the DOMCMDS and DOMPILES aggregates in torms of what files execute whae commands. This is shown as below: DONCMDS: NEW < DOMFILES: NEW < Vesti "CHACRO" » ‘FULEDIT" » {CFULEDIT" sEXIT! »CEXIT" +‘ TOP" »"CTOP" »'BOTTOM" CROTON" > ‘BOT! »CBOTTOM" » "REFRESH » CREFRESH' As you can see, this is the DOMFILES aggregate for the CON domain because each of the execution files starts with a "C" to differens tiate it from the execution files for other domain commands. In ad. dition, we note that although each command may have a number of synonyms such as in this case "BOT" and "BOTTOM" represent the same command "BOTTOM", the execution file for each is the same. preenGer to support these new facets of the system we will change PREPROC so that it can pass some more information to PROCCMD when the command is to be interpreted. The modified PREPROC is shown ben low with the modifications indicated: PREPROC: SUBR(CMDLINE) ; ‘TEMPLINE: NEW LBLANK(CMDLINE|* * CMDTOKEN: NEW INT; this identifies the index of the cmd in DoxcMps BPOS: NEW LOCSTR(' ' ,TEMPLINE) ; CMD: NEW SUBSTR(TEMPLINE, 1,BPOS-1) ; ARGLIST: NEW SUBSTR (TEMPLINE , BPOS+1 , LENGTH (TEMPLINE )-BPOS) ; IF CMD BQ <'',' '> THEN BRANCH(LOOP) ; IF CMDTOKEN = MEMBER (CMD, DOMCMDS) ‘THEN PROCCMD (CMD ,CMDTOKEN , ARGLIST) determine CMDTOKEN the important information is passed to PROCCND ELSE BEGIN MSGOUT(' INVALID COMMAND' ,TEMPLINE) ; BRANCH (LOOP) ; END; END; 16 RPD: System Manual'BM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* Using the new variable CMDTOKEN which identifies the exact string in DONCMDS which matches the conmand (CMD) we can pass this information fo PROCCMD which can then unambiguously extract the proper command execution file from DOMFILES Therefore, we can almost visualize what PROCCMD should look Like. Incidentally, PROGCMD is not explicitly called in the subroutine START. Instead, PROCCMD is called by PREPROC whenever it is finished with processing the line command. At least we know what it major responsibilities are can define those as follows: 1) find the command execution file corresponding to the inputted command 2) load the command execution file 3) execute the subroutine in that file 4) after execution has completed erase the the execution file subroutine from memory. According to this the implementation of PROCCMD is very straight forward. Basically you create a variable to hold the name of the execution file; load that file with the subroutine that bears the SAME name; execute that subroutine and finally unload the subrou. tine. The following coding example does exactly that. (Note: this 48, of course, just a fragment of the real PROCCMD subroutine which includes provisions for generalized command error handling and mac~ ro execution... it may be interesting to compare this version with the real one and see what is involved in integrating these features into the system structure). PROCCMD: SUBR(CMD ,CMDTOKEN, ARGLIST) ; FN: NEW STRING(8) ; CLEANUP (*PROCCIN") ; -> make sure to unload ++ the execution subr >> upon exit LOAD(£n = domfiles(cmdtoken)); -- load the exec file EVAL(EN) ; -+ eval the subr RETURN; PROCCIN: SUBR; UNLOAD(EN) ; ++ unload the subr END; END; What wo have discussed is the essential system structure supporting line commands. This is important because we will find that line conmands, simple as they are, constitute a rich form of interaction between the user and the system. ‘LINE COMMAND PROCESSING AND THE SYSTEM KERNEL 17'BM INTERNAL USE ONLY - DRAFT ** DO NOT Copy ** To summarize let us describe the way a line command travels from the keyboard through the system kernel, in particular the three impor= tant routines: READCMD PREPROC and PROCCMD The command is entered on the command line using a simple read loop in READCMD that will continue to loop unless the user actually ene ters an input line. READCMD then sends the input line to the coms mand preprocessor PREPROC which, anong other things, separates the input line into command and argument fields, determines the validity of the command, provides for necessary error recovery and passes various command interpretation information to the command processor PROCCMD. PROCCHD then leads in the proper command execution file completing the processing of the command. This loop READCMD --> PREPROG --> PROCCMD is repeated again through each loop of the sys~ tem kernel. A discussion of the actual execution of the command in the execution file and how it relates to the domain environment is the subject of the next part of this implementation guide. 18 RPD: System ManualIBM INTERNAL USE ONLY - DRAFT * DO NOT Copy #* 3.0 COMMAND EXECUTION AND THE DOMAIN ENVIRONMENT 3.1 INTRODUCTION According to the last chapter we have developed a scheme which de- Codes @ command submitted by the user and produces a correspondence between that command and some execution file resident on disk. All the previous processing was done within the systen kernel which must always be present in the systen in order to process commands. Now, We must leave the system kernel and develop some sort of scheme to make these commands do what we want them to do. But what do we want them to do? What should these conmands do and upon what should their effects be realized? Well, as far as we're Soncerned it doesn't seem like these commands can really do anything Significant. All we have at this point is a handful of routines is the system kernel and a few IPL files. 3.2 A SAMPLE COMMAND AND ITS EXECUTION CYCLE But for now, we will illustrate what one of these command execution files look like and what it does, because even at this point we can devise a command which can do something potentially useful. Remember the MSGOUT routine that is resident in the system kernel? It was the one that the system used to pass messages to the user gbout various important things going on the system. Certainly in- forming the user that he has committed an error seems to wasrant ecgun Out a message on the message field of the screen using NSGOUT. In fact, the MSGOUT routine does not have to solely serve System needs only. Commands and other (as of yet not specified) Parts of the system can also send messages through USGOUT to the us~ er So, with this in mind, we will create a command called MSG that sends @ user-defined message to the user through the message field (lines 19 and 20) on the screen. The execution of this conmand would use MSGOUT in the same manner as the system kernel uses MSGOUT fo send messages. At first glance this conmand may seem to be quite useless. However, this conmand will prove in many cases to be very useful within macros (written in the extended development language COMMAND EXECUTION AND THE DOMAIN ENVIRONMENT 19'BM INTERNAL USE ONLY - DRAFT ** DO NOT Copy ** DESIGN/AML) when they need to inform the user of what is going on or fo Prompt the user when interactive input is needed. The message that will be sent out will be in the argument field of command; hence the command execution file will make use of ARGLIST that was gzeated by PREPROC and passes to the conmand execution file by PROCCMD So let us write this very first command execution file. First of all, what do we know about such files? 1) It mist contain a subroutine of the same name that executes the command 2) It must interact somehow with various elements of the system. Obviously, in the CON domain we will call this file CMSG and the subroutine within it OMSG as well. So the following is the code for the MSG command execution file: MSG: SUBR; MSGOUT( "USER MESSAGE END; ,ARGLIST) 3 This code is different than the real example because the author now realizes that this version is better both for implementation and dow Cumentation purposes. Both versions will do the same thing, but this one will do it faster. The first message on line 19 indicates that this is @ message generated by the user and the second message is the argument to the command. Certainly this seems simple enough, but to put it in perspective let us review the sequence of events leading up to and including this conmand execution file. Firstly, READCMD will allow the user to enter the conmand on the in put line by displaying the appropriate prompt and waiting for input. The bottom part of the screen will look like this (after the user types in the command): CON => CSG HELLO Pressing the Enter key sends this command as an input line to READOMD which then sends it to PREPROC for further processing. PRE- PROG will then remove any leading blanks (there are none in this case) and find the position of the first blank in the input line at position 4. This then splits up the input line into the two fields CHD which is now 'MSG' and ARGLIST which is now ‘HELLO’. Upon finding that MSG is included in the command directory for the CON domain, PREPROC will call PROCCMD and supply it with important ine 20 RPD: System Manual1BM INTERNAL USE ONLY - DRAFT * DO NOT Copy # formation for execution namely CMD, ARGLIST and CMDTOKEN which is the position of MSG within DOMCMDS, the conmand directory for the CON domain. PROCOMD then finds that the name of the command execution file for MSG is "OMSG' and it thus loads this file into storage. Loading the GNSG file also loads the CMSG subroutine which is then executed by PROCCMD. Executing CUSG will produce the following results on the screen, through the routine MSGOUT (a part of the system kernel): CON => sk USER MESSAGE HELLO > MSG HELLO After this, control returns to PROCCHD which unloads the execution subroutine and enables the system kernel to continue through its loop. 3.3. THE FULL-SCREEN DOMAIN ENVIRONMENT -- INTRODUC- TION Although the above discussion has demonstrated the feasibility of implementing these command execution file structures, we have not yet demonstrated any significant usefulness for these commands. But that is to be expected since we don't have as yet the facilities to express any useful functions that may be performed by such com mands. To do so we must create a need for such commands and an environment that enables these commands to satisfy the requirements of those needs. For now we will assume that our domain will serve the purpose of allowing the user to perform simple editing functions on a text file. The environment that supports such a function must do things such as display parts of the file to be edited and enable to the user to manipulate parts of the file during the editing process. Since we will be later discussing the full-screen aspects of the system as well as the associated prefix commands, we will use the screen display that is part of the full-screen support module that comes with many of the domains in the system. Let us assume for now that our text file has been enabled for editing by the following AML statements: EDITFILE ('NEWPROG') ; GETLINE (FIRSTLINE) ; COMMAND EXECUTION AND THE DOMAIN ENVIRONMENT 21IBM INTERNAL USE ONLY - DRAFT ** DO NOT Copy ** The idea now is to take this editing object and somehow project it on the screen so that the user can examine its contents. for the Purposes of the full-screen support module the screen, will in fact resemble something like the XEDIT screen in CMS (The TBM Conversa tion Monitor System that runs under VM) 3.4 PREPARING THE SCREEN DISPLAY Due to the restrictions of the screen size our screen will support enly 15 lines of text, including an embedded text scale (or rule) that serves to help the user in keying in programs and data as well as indicating where the current line is on the screen. Although in the future the emphasis will be on full-screen editing, the current line concept will still be very important for certain editing operations. Other lines on the screen are taken up by the command line that is controlled by READCMD, the message line that is controlled by NSGOUT and two header lines on the top of the screen that display some other important information from the editor. There are a number of considerations to take into account for when Preparing the display: First of all, the display must the centered around the current line. In other words, if the first line comes between the top of the screen and the current line then there must be some blank lines between the top of the screen and the top line. Furthermore the same holds for lines below the current line, and this may imply blank lines between the last line in the file and the bottom of the screen. The extreme cases are when the current line is the first line in the text file and when the current line is the last line in the file. In preparing the display we must also take into account the the future use of the screen in full-screen mode. Therefore we must somehow keep track of what lines have valid text on them , which are blank lines, and which line has the scale on it. Finally, in antic. dpation of prefix commands which are the full-screen ‘equivalent’ of line commands we must have provisions to display a prefix command area on either the left or right sides of the file Basically the algorithm that performs these functions is very simple and is elucidated below: 1) display the header information on lines 1 and 2 of the screen 2) find out what the first line to be display is on the screen and thus how many blank lines must appear between the first line displayed and the top of the screen (line 3) 22 RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT Copy #* 3) Prepare the display screen buffer FULSCR by entering into each line of FULSCR either a text line, a blenk line or the scale (which appears on line 8, just below the current line). 4) If a text line is to be prepared append the prefix command area on either the right or the loft according to the variable PRXA. 5) The vertical position of the scale is also affected by the value of PRXA and the column position is also put in the right position according to the variable COLPOS. The column position is important in commands that manipulate individual characters in the current line. The code for this looks as follows: Incidentally we have a number of variables that are initialized either in the domain IPL file or when the full-screen support module is loaded. They are COLPOS (the cole sr cpositioner), SUBRNAME, (the name of the current editing object), APPLEVEL (the current level at which the subroutine is rane ning, FULSOR (which is an aggregate of strings representing the screen display), LINEVECT (which is an aggregate of integers indicating the properties of each line in FULSCR) and PRXA (which as wo mentioned indicates where the prefix area should be on the display). COMMAND EXECUTION AND THE DOMAIN ENVIRONMENT 23IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* FULPREP: SUBR; Sl: ‘TLINE: NEW INT; ‘TRACTOR: NEW INT; CLINE: eee PUTSTR("|' ,SCALE,COLPOS, 1); POINT(O, 1); DISPLAY('#" FULL-SCREEN EDITOR #** SUBROUTINE: ',SUBRNAME, ' AT LEVEL: ',APPLEVEL,EOL) ; IF (TLINE = NEXTLINE(~6,NEARTOP)) LT FIRSTLINE THEN TLINE = FIRSTLINE; GETLINE (LINE (TLINE-1)) ; TRACTOR = (REPEAT I = I + 1 UNTIL NEXTLINE(I) EQ CLINE) - I= 05 WHILE 16 - (I= 1+ 1) Do IF <7-I GT TFACTOR,CURLINE GE LASTLINE> ‘THEN BEGIN IF 8-1 THEN BEGIN FULSCR(I) = STRING(79); LINEVECT(I) = 03 END ELSE BEGIN IF PRKA THEN FULSCR(8) = SCALE|' ' ELSE FULSCR(8) = ' *|ScaLE; LINEVECT(8) = -1; END END ELSE IF 8 - I ‘THEN BEGIN IF PRXA ‘THEN FULSCR(I) = (STRING(72) Is GETLINE (NEXTLINE) | STRING(72)) |" =====" ELSE FULSCR(I) = '===== '|(STRING(72) 18 GETLINE (NEXTLINE) | STRING(72)) ; LINEVECT(I) = CURLINE; END ELSE BEGIN IF PRXA ‘THEN FULSCR(8) ELSE FULSCR(8) LINEVECT(8) = -1; END; SCALE|" ' q "SCALE; GETLINE (CLINE) ; RETURI NEARTOP: TLINE = FIRSTLINE; 24 BRANCH(S1) 5 RPD: System ManualIBM INTERNAL USE ONLY - DRAFT #* DO NOT COPY #* END; COMMAND EXECUTION AND THE DOMAIN ENVIRONMENT 25IBM INTERNAL USE ONLY - DRAFT ** DO NOT Copy #* A brief explanation of this subroutine follows: The first part initializes some important local variables. TLINE is the line number of the very top line in the display TFACTOR is the number of lines including the current line that is to be displayed above the scale CLINE stores the line number of the current line I is a counter used both for calculating TFACTOR and for generating all 15 lines in the display SCALE of course is the scale. This is a variable since the scale column position may change according to COLPOS The next Line (PUTSTR("|' SCALE ,COLPOS,1);) places the column position in its proper place on the scale which will be displayed on line 10 of the screen. ‘The next three lines (two statements) in the subroutine prepare the header. (Note: it was planned that the processing of the header should be contained within another subroutine S0 that more intelligence could be ascribed to the header processing (i.e. more information indigent to the particular display could be incorporated in the header)). In any case, the following "IF" statement calculates TLINE, the top line in the display. We then "GET" the line before this (with the intention that we will actually generate the next line) and calculate TFACTOR, the number of lines to be displayed above the SCALE. TFACTOR is important because we now can generate a display that is centered around the scale. The Presupposes some knowledge about the number of lines to be displayed, and the number of lines that are left blank; TFACTOR (and LASTLINE) gives us this knowledge for the top and bottom cases respectively. The most important part of FULPREP is the "WHILE" loop that takes up most of the processing (and space) in FULPREP. Essentially, it pro cesses and generates all 15 elements of the FULSCR aggregate (each element being a 72 character string representing a single line on the screen), The loop variable, I starts at 0 and is incremented before each iteration until the value reaches 16. During each of these iterations the context of the line to be generated is tested. That is each line is tested as to whether it is outside the text block (i.e, either below the last line to be displayed or above the first line to be displayed). This test is incumbent upon two conditions: TFACTOR is involved, and so is the relationship between the last line in the text and the continually incremented current line. This test is reflected in the "IF" statement that composes the "Will LE" loop. That is if the line to be generated is above the text block (the case when 7-I is greater than TFACTOR) or if the line to be generated is below the text block (the case when the current line is greater than or equal to the last line). In the latter case we 26 © -RPD: System Manual'BM INTERNAL USE ONLY - DRAFT ** DO NOT Copy ** check for equivalence between the current line and the last line because, if you recall, the line to be generated in the display corresponds to the next line after the current line point which is continually incremented after accessing each line. In any case, if we do find that or display line is outside of the text block, then we will change FULSCR(I) (the Ith element of FULSCR) to either a blank line or to the scale which of course is always on the 10th line of the display (the 8th element of FULSCR, which accounts for the fact that the top two lines of the display are taken up by the header, FULSOR being a representation of only the screen that poses as a window for the text to be edited). Otherwise, if the two conditions specified involving TFACTOR and TASTLINE do not hold, then we have encountered a valid line within the text block and must generate FULSOR(I) appropriately. This also means that we must process both the text line and the prefix command area (which may, of course, be resident on either side of the text Hine depending on PRXA. This text line is prepared only when the line is not the eighth line in FULSOR. The text line is generated by "getting" the noxt line and appending that to the prefix command area (either on the right or the left) and taking that whole string and putting it into the Ith element of FULSCR. In the other case. the scale is prepared (of course we may have the scale embedded within the text block, which is what this particular case takes care of). The subroutine ends by resetting the current line back to CLINE which was saved upon entry into the subroutine. At this point FULSCR is fully processed and ready to be displayed on to the 3.5 DISPLAYING THE EDITING OBJECT AND PERFORMING COM- MANDS, The task of displaying the fully prepared screen representing the Current editing object is now very simple and is taken care of by the following subroutine FULDISP: FULDISP: SUBR(START DEFAULT 1,LAST DEFAULT 15); I: NEW START - 1; POINT(O,START + 2); WHILE (I = I + 1) LE LAST Do DISPLAY (FULSCR(I), EOL) ; MSGOUT; END; This subroutine allows for the selective display of only certain continuous lines in the display in order that the speed of the sys- COMMAND EXECUTION AND THE DOMAIN ENVIRONMENT 27'BM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* tem maybe somewhat improved through the judicious use of screen refresh. Hence, when the subroutine is called, both the starting line of the display is specified (START) in reference to FULSCR and not in reference to the whole screen, and last line of the display is specified (LAST) also in reference to FULSCR. The job of the subroutine, then, is to point the screen to the first line to be displayed and then display continuously from START to LAST those lines {hat are specified to be displayed. This is performed by the "WHILE" loop iterating through the display of each line in the screen. What we have now is a simple domain environment; one which takes the elements which we wish to operate on and allows us to see the oper= ations on those elements. In this case the elements constitute some text to be edited which may be a macro definition, a source program, 4 point definition file etc. The uniqueness of each of these applications is determined by the operations that are performed on the editing objects respectively. These operations are none other than the conmands and their execution which we described in detail earlier. Let us assume, for now, that the editing object represents a macro (written in DESIGN/AML -- the development control language for the Robot Program Development System) in the process of being defined. We would certainly want some of the operations being performed dur~ ing this definition to correspond to standard editing operations indigenous to other editors. In fact, many of these operations are reflected in the commands supported by the current implementation of the macro editor. Let us examine one of these commands, its implementation and its interaction with the domain environment. As you might recall, the key to understanding how @ command is in= terpreted is in the execution file corresponding to that command. The command execution file controls the interaction of the command with the domain environment and hence its operational significance As an example, let us examine the command execution file for the "TOP" command in the macro editor. The file looks as follows: MTOP: SUBR; IF CURLINE - FIRSTLINE THEN BEGIN GETLINE (FIRSTLINE) ; FULPREP; FULDISP; END; MSGOUT('TOP OF PROGRAM"); END; When PROGOMD loads in NTOP it begins to execute the corresponding Subroutine MTOP. The execution is simple: If the current line is not the first line then we will "get" the first line and refresh the 28 PD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** whole display. Because the screen may totally change because of reaching the top of the text, it becomes necessary to refresh the entire screen rather than the more prudent strategy of refreshing only portions of the display. Following this a message is sent to the screen (through the message field on lines 19 and 20) indicating that the current line is now set to the top of the program. If we execute this command in the case when we are already at the first line, it becomes unnecessary to refresh the whole screen; in this case, we merely output the appropriate message rather than indulg- ing in all the unnecessary processing. The difference between this command and the one we demonstrated earlier (namely the MSG command, that output a user defined message on- to the message field of the screen) is that this command interacts both with the system kernel and with the domain environment that we just set up. We can see that it interacts with the system kernel through the MSGOUT call. Furthermore, it interacts with our domain environment through the FULPREP and FULDISP routines as well as through directly changing the editing object with the AML statement: GETLINE (FIRSTLINE); On the other hand, the MSG command solely interacted with the system kernel through MSGOUT and had no effect on any sort of domain envi_ ronment, the fact being, of course, that such a domain environment hadn't been established yet. In order the give a better flavor of what these command execution files look like let us look at another command which interacts with the domain environment in a more complicated way. The command which we will examine will be the CDELETE command which works in essen tially the same manner as the CDELETE command works in the VM/SP editor XEDIT. In brief, the CDELETE command is used to delete one or more characters from the current line (the one above the scale), starting at the column pointer. The format of the CDELETE command is as follows GDelete ( column-target | 1) The column target (which in this case defaults to 1 if it isn't specified) defines the number of characters to be deleted. Deletion of characters in the current line starts at the column pointer and con~ tinues up to, but does not include, the column-target. This command is useful because it allows the user to operate on specifie charac= ters in the current line with the double advantage of precision and speed of editing ‘This command mst, therefore, do a number of things: 1) it mist determine the column-target according to the current column position and the following four different conditions: COMMAND EXECUTION AND THE DOMAIN ENVIRONMENT 29IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** 4) if no colum-target is specified (that is, there are no arguments to the command) then the default value of +1 must be calculated, The target column pointer will thus be one greater than the current column pointer or COLPOS + 1 b) if a relative column-target is specified then that must be computed (both in the case of a positive relative column-target Which indicates a column-target to the right of the column pointer, and the case of a negative relative column-target which, of course, means a column-target to the left of the current column pointer. ¢) if an absolute column-target is specified (i.e. a number preceded by a ":") then this must be computed. 4) finally, if a string argument is specified (the string must be delimited by two slashes "/"), then the string must be located in the current line and, if there, the column-target for the column position of the string mist be computed. 2) if an error in computing the column target occurs, than the appropriate error message must be output and execution terminated. 3) the command must then delete the number of characters specified by the computed column-target. 4) the column pointer must be reset to the computed column-target. 5) the command must then refresh the appropriate parts of screen (refreshing, of course, means both preparing and displaying the screen). The command execution file named "MCDELETE" does the job. Remember, that the system kernel knows which command execution files corre. spond to which commands through the one-to-one correspondence between DOMCHDS and DOMFILES (a correspondence that is established in PREPROC with the subsequent assignment of CNDTOKEN) . MCDELETE: SUBR; COLTARG: SUBR(TARG); IF TAKE(TARG,2) EQ <"* ",'4'> 30 -RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** THEN RETURN(72) ELSE IF TAKE(TARG,2) EQ ‘~#' ‘THEN RETURN(1); IF SUBSTR(TARG,1,1) EQ THEN RETURN(CVTSN(SUBSTR(TARG, 2, LENGTH (TARG)~1) ,NEER)) ELSE IF SUBSTR(TARG,1,1) EQ '/' HEN RETURN (LOCSTR (SUBSTR(TARG,, 2, LENGTH (TARG)-3), GETLINE (CURLINE) ,COLPOS) ) ELSE RETURN(COLPOS + CVTSN(TARG,NEER)); END; ARGS: NEW LBLANK(APPLY("|' ,PROCARG(ARGLIST))) ; I: NEW INT; STR: NEW GETLINE(CURLINE) ; IF ARGS EQ '' ‘THEN I = COLPOS + 1 ELSE I= COLTARG(ARGS); IF (I LT 1) oR (1 GT 72) ‘THEN BEGIN MSGOUT('TARGET NOT FOUND!) ; BRANCH (LOOP) ; END; IF I GE coLPos THEN CHANGE (STR,SUBSTR(STR,1,COLPOS - 1)| SUBSTR(STR, I , LENGTH(STR)-1+1)) ELSE BEGIN CHANGE (STR, SUBSTR(STR,1,1) | SUBSTR(STR,COLPOS + 1,LENGTH(STR) - COLPOS)); cOLPos = END; IF PRXA, THEN FULSCR(7) = (STRING(72) IS GETLINE (CURLINE) | STRING(72)) |" "| (STRING(72) IS GETLINE (CURLINE) |STRING(72) SCALE: NEW STRING(73) IS '<..04....10.04.0.2ice, 5. ELSE FULSCR(7) Hee. a4] PUTSTR('|' SCALE ,COLPOS,1); IF PRXA THEN FULSCR(8) ELSE FULSCR(8) POINT(0,9) DISPLAY (FULSCR(7) ,EOL,FULSCR(8) ,EOL) ; END; SCALE |" ' ° "SCALE; COMMAND EXECUTION AND THE DOMAIN ENVIRONMENT 31IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** Obviously this conmand execution file is more complex than the the ones we have seen before, and deserves a more detailed explanation The first statement (not including the nested subroutine definition COLTARG which will be discussed later) processes the arguments to the command. Basically, it removes ali leading blanks from the ar~ guments (NOTE... this code is an exact copy of that on the diskette, but a more up to date and common sense version of this program Line would be as follows ARGS: NEW LBLANK(ARGLIST) ; Remember that PROCARG is only used in the case of multiple arguments to the command and serves the purpose of a generalized argument par~ ser. In addition, the old form of this program line does not allow the string representation of the column- target to have any embedded commas . ) In any case, we set I to be the absolute column position of the column-target. In the case of the default value it is set to COLPOS + 1, otherwise the colum-target is computed using the nested subroutine COLTARG. COLTARG first, checks for extreme relative values in the form of Ne/"4e" or “x and returns 72 (the right-most column pointer value) or 1 (the left-most column pointer value) respectively. It then checks for absolute column pointer values through the delimit~ ex '":", The branch to NEER in this case when the conversion to nu- meric form fails is a branch back to PROCCMD which contains some generalized error handling code. If the column- target is not specified as absolute, then the column-target is checked to see if it corresponds to a search string value. This is processed through the LOCSTR statement which returns the absolute column position of the string if found and returns a 0 if the string isn't found. Finally, if no column-target has yet been returned, a relative column-target is assumed and is computed. After computing the column-target, the next statement checks for an invalid column-target value (indicating that the target wasn't found). In this case the appropriate message is output to the mes~ sage field on the screen. The next step is to delete the specified sequences: of characters upto and not including the column-target. This is done by the two CHANGE statements, each of which correspond to either the column-target being to the left of the current column position or to the right of the current column position. Furthermore, if the column-target is to the left of the current column position, then the current column pointer must be changed to reflect this Finally, we prepare the screen for refresh. Of course, since we only changed the current line and the scale it is only necessary to update FULSCR corresponding to the current line and the scale (name 32 -RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** ly lines 7 and 8 in FULSCR, lines 9 and 10 on the screen). In addition our update is contingent on whether the prefix command area is to the left or to the right of the text block a condition specified by PRXA. When the preparation of the screen is complete, we need only display those portions of the screen which have been updated. This is reflected in the last line of the conmand execution file which performs the display itself after setting the screen pointer to the 9th line on the screen. Essentially, then we have almost completed the discussion of line commands and their role in the system. To summarize, we may note that line commands and their interpretation are controlled by command execution files which when called by PROCCMD and executed by PROCCMD interact with the system kernel and the domain environment in ways meaningful to the system. In particular the interaction with the domain environment is the more important because it is a dynamic relationship dependent on what the domain environment is actually composed of and represents. In other words, the commands and their interpretation will most definitely change according the domain environment in which they are invoked. In particular we discussed one of these domain environments: a general framework for a full-screen editor display. We showed, twice, how command execution files would interact with this environment, within the context of the domain performing as a macro definition editor. Our next logical step in the description of the system could take either of two forms: we could enhance the domain environment to de- monstrate full-screen capabilities, in particular the execution logic of full-screen prefix commands, or we could discuss the execution of macros and their role in the system. The course we will take is the latter, primarily because it involves ideas that deal with the system kernel, in particular PREPROC and PROCCMD and have further ramifications for the system as a whole. COMMAND EXECUTION AND THE DOMAIN ENVIRONMENT 33IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* 34 -RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* 4.0 DESIGN/AML, MACRO DEFINITION AND MACRO EXECUTION 4.1 INTRODUCTION In this chapter, we will go back to the system kernel in order to develop a scheme for the implementation of macros in the system. ‘To start off, though, we will discuss what these macros are and what they are used for. ‘These considerations will, of course, influence their implementation. There is of course, no one implementation scheme for this problem. Indeed, in order to clarify our points in more detail we will also discuss aspects of alternate implementation schemes in this respect. Note: in the discussion the term “macro” and "DESIGN/AML program" are synonymous. 4.2 DESIGN/AML AML (A Manufacturing Language) is designed to support four aspects of Robot Programming: 1) Motion control 2) Sensing 3) ~ ca 4) Data Processing Each of these in combination with the others plays an important role in a robot application. The important consideration is that motion is not the only aspect of robot programming and that robot programming involves more facets than may be imagined at first glance. The idea of DESIGN/AML is that AML should be able to support a fifth aspect of robot programming, namely robot program development. The present AML system for the IBN 7565 Robot system does support development aids that are integral to the language. It is intended that in DESIGN/AML the language be separate from the system so as to be general but still very tightly integrated in the sense that all the facilities provided by the system may be accessed by the macro language program. In other words, let us imagine our whole development system consist- ing of a single domain which allows the user to interactively invoke exactly 50 line commands. Each of these commands may be entered in- DESIGN/AML, MACRO DEFINITION AND MACRO EXECUTION 35IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY # teractively at the terminal using the input line that is scanned by READCMD. All this, of course, should be familiar. However, it should also be possible to put these commands in the form of a macro such that a string of commands each executing one after the other may be processed consecutively. Furthermore, it is desirable that this macro language possess some sort of control constructs that allow the structuring of line command strings. These constructs could be selection structures in the form of IF...THEN...ELSE, or loop structures in the form of of WHILE and REPEAT loops. AML is a natural choice for a language that supports these features. Indeed, it is even move desirable that we embed these line commands within a Separate AML program that can execute these line commands according to the structure specified. This separate AML program would then be augmented in terms of its power and facility by the combined 50 line commands that can be used by the program. Thus this program can perform useful tasks such as editing, debugging and testing of robot programs in an automated and systematic manner. An important point is that this separate macro program is a modified AML program but an AML program nonetheless; however, it is NOT the same program (nor is it part of) as the application AML robot program that is being developed. They are two Separate programs although the DESIGN/AML program can modify the application program or influence its execution in many ways. ‘The power of DESIGN/AML is even more pronounced if we have a development environment with a number of domains supporting a number of robot programming languages and each domain having a hundred or so commands in its repertoire, The DESIGN/AML program should be global in the sense that it can jump from domain to domain within the program. Furthermore, if we have the facility of being able to call other macros within a macro, as well as the ability to call macros interactively, then we can structure our DESIGN/AML program as well as develop a library of system-wide macros that greatly expand and extend the power of the system as a whole. What we have then is a powerful tool for the system-wide integration and automation of robot program development. To give an example of a simple application of a DESIGN/AML program, let us consider the following example: ‘This DESIGN/AML program can be considered to be an extended version of the standard CON domain RUN conmand. It selectively sets the trace mode and executes the program pending interactive screen input of certain motion parameters. EXRUN: SUBR; IF TRNODE EQ 0 THEN BEGIN % TRACE ON END; 36 -RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* MSG PLEASE ENTER VALUES AS REQUESTED SPEED ACCEL DECEL SETTLE TOP RUN END: oF ge a8 ae ae a8 20 28 Most certainly, applications of macros in the way of robot program development will be more sophisticated. 4.3 SOME POSSIBLE IMPLEMENTATION SCHEMES If we recall that the execution of each line command is controlled by a corresponding command execution file, then we can use this fact to come up with some sort of execution scheme for macros. That is, would it not, be possible to compile a macro in such a way that a macro "object" file would be set up with each line command in the original "source" macro being replaced with an exact copy of the command execution file for that command. For example, if we have the following statement which deletes 5 characters in the current line starting from the current column pointer and proceeding to the right. ODELETE +5 We discussed this command and its execution file in the last chapter. According to this implementation, then, the object DESIGN/AML program would contain embedded within the AML code the conmand execution file. A number of problens can be inmediately seen with this implementation. First of all, the object macro will be necessarily very large compared to the source program thus placing excessive demands on the Series/1 computer storage. Another, more serious problem is that the code (corresponding to the command execution file) that executes the command will necessarily contain local variables that would perhaps interfere with variables local to the DESIGN/AML progran. For instance , if the macro had a counter named I, then the same I that we discussed in the last chapter that computes the absolute position of the colum-target in the command execution file for CDELETE would necessarily have adverse affects on the macro defined I. Finally, a macro could possibly be called from any one of a number of domains, such that the same macro could be used interactively from each domain, depending of course on the nature of the macro. DESIGN/AML, MACRO DEFINITION AND MACRO EXECUTION 37IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* In this case the macro is said to have multiple invocation contexts. The above implementation would not allow such multiple invocation contexts, since only one version of the command execution file could be coded in the object code version of the macro. That is, our macro could invoke the TOP command in either the macro editor or the AMLEE CON editor or the AMLEE full-screen editor etc. Although the meaning of the top command is the same in each, namely the command causes the current line to be the top of the editing object, its implementation in the form of command execution files is different in each of the above cases. In order to keep our macro object files small, generalized and inde- pendent from our objects of development, we must reevaluate our implementation scheme. In particular let us examine what processes take place during the execution of macros. So far @ macro can be said to consist of two parts. First of all a macro is inherently an AML program so the first of these parts is the AML program statements themselves. They execute exactly as they are specified. The second part of a DESIGN/AML macro is the embedded domain line commands that determine the how the macro interacts with the domains in which it is operating in. Somehow the process~ ing of this portion of the macro must involve the command execution files for the line commands. This was recognized earlier but imple~ mented in an unsatisfactory manner. looking, at the case of interactive execution of line commands, we see that this is achieved by calling PROCCMD which then loads the proper command execution file. PROCOMD is, of course, called from PREPROC which takes the result of READCMD. What we can do with the macro then is to actually invoke the system kernel whenever a line command is encountered. In effect to sides~ tep the READCMD routine and trick the system kernel into thinking that it is processing an interactively invoked line command. Let me explain further: Suppose, our line command embedded in the macro is as follows: CDELETE -¥ This instruction would erase everything from the current column po= sition to the very first character (not inclusive) in the current line. The object file of our macro, instead of containing the actu~ al command execution file for CDELETE, could contain a call to PRE~ PROC (in the system kernel) to process the command. In essence, then @ domain command line in the macro would superficially resemble the input line for interactive input. Thus, the object file of our macro would contain the following AML statement which would in effect execute CDELETE as we specified it: PREPROC('CDELETE ~*") As you can see, the process of compilation is as simple as taking each line with a domain command in it and concatenating it with a 38 —-RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* 3’ and placing predetermined string of the form 'PREPROC(' and this in the object file. This scheme, of course, would work perfectly but for the fact that PREPROG is a relatively slow routine. Remember, that it must search an aggregate of strings DOMCMDS (the aggregate that corresponds to a dictionary of all the valid commands and their synonyms in the domain) and do other time consuming tasks such as removing excess leading blanks, splitting up the command field and argument field, etc. All this processing is done to make the job of PROCCMD as sim= ple as possible, that of loading the proper command execution file and executing that file. Since the problem with line command execution in macros is simply that of loading and executing the proper command execution file, then would it not speed the process of macro interpretation faster, if the compiled version included a call to PROCCMD rather than PRE~ PROG? Therefore, if we call PROCCMD, the process of compilation should then be a process of mimicking the action of PREPROC and creating an object file that continually calls PROCCMD for each domain Line command encountered. Such a compiled line would look as follows: PROCCMD('CDELETE', ,'=*"); The three passed values being computed upon compilation. A prototype compilation routine that could either be used in a straight forward compilation phase of macro definition, or alterna- tively an interpreted phase as the macro is edited, or a combination of both with interpretation being used solely to check for invalid commands is shown below: Note... the latter scheme would be the best from both the user and the implementation point of view, the first being difficult on the user, and the second being difficult to implement in a full-screen editing environment. LINECOMP: SUBR( INLINE) ; IF SUBSTR(INLINE = LBLANK(INLINE),1,1) NE '%" ‘THEN RETURN(INSERT(INLINE)) ; TEMPLINE: NEW LBLANK(DROP(INGINE|" ',1)); CMDTOKEN: NEW INT; ARGLIST: NEW STRING(72) ; BPOS: NEW LOGSTR(' ' ,TEMPLINE) ; CHD: NEW SUBSTR(TEMPLINE,1,BPOS-1) IF OMD EQ <'',' '> THEN RETURNCINSERT(' ')) ELSE BEGIN ARGLIST = SUBSTR(TEMPLINE, BPOS+1, LENGTH (TEMPLINE) -BPOS) ; IF CMDTOKEN = MENBER (CMD,EVAL(DOMAIN| 'CMDS")) THEN RETURN(INSERT('PROCCMD(" | GVINS(CMDTOKEN) |", ''' |ARGLIST|''');*)) ELSE IF MEMBER (CMD ,EVAL(DOMAIN| 'MCL")) DESIGN/AML, MACRO DEFINITION AND MACRO EXECUTION 39'BM INTERNAL USE ONLY - DRAFT ** DO NOT Copy ** THEN RETURN(INSERT(' PROCCMD(1,"** | arcList|''*);*)) ELSE RETURN(-1); END; END; Since this routine has not been actually integrated with the macro definition domain (although, of course, it is an integral part of the macro definition domain), I will refrain from an in depth discussion of its inner workings. A short summary, though, starts from the first line which checks if a line is either an AML statement or @ domain line command; it does this throngh the marker "&" that pre- cedes every domain line command in a DESIGN/AML program. It is intended in the future, that such a marker not be required and rather the LINECOMP routine should contain the intelligence to discern whether the macro statement is that of AML or of a domain command. Incidentally, the name of this compilation routine is LINECOMP simply because of the important fact that this is a line-by-line compilation process (mich like an assembler). If the DESIGN/AML statement is actually an AML statement then the routine inserts this statement (as it is) into the object file (which is now the editing object). From there on it is assumed that the macro statement is potentially a domain line command. Since we said earlier that the compilation process would resemble PREPROC, we can see indeed that the rest of LINECOMP has a distinct resemblance to PREPROC in the system kernel. The three important values: CMD, ARGLIST and CMDTO- KEN are generated in the same manner as in PREPROC. As you recall, these three values are sent to PROCCMD as vital information for the Proper interpretation of the line command. The only differences are that LINECOMP, instead of calling PROCCMD, creates a call to PROCCND by concatenating the appropriate strings in the macro object file. 4.4 MACRO INTERPRETATION AND EXECUTION Essentially we have described both how macros are defined and compiled. But the interpretation of macros is yet unclear. Obviously, the execution of a macro requires running the macro object file since in its compiled form a macro is a valid AML, subroutine (i.e. there are no domain line command markers such as "%"). How does the system kernel then know that the macro is both a macro (not a line command) and @ valid macro at that (that is one whose context is defined in the domain in which it is invoked)? These are problems that were also encountered with line commands in the first chapter of this implementation guide. As in the case of line commands, we will use PREPROC to solve this problem. 40 PD: System Manual18M INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* What we need then is some part of PREPROC that determines two things: 1) is this input line a macro? and 2) if so, is it a valid macro? First of all, we know that if the input line is a line command, then the command field (CHD) will be found the line command dictionary, DOMCHDS. Otherwise, we can assume that the input line represents a potential macro to be interpreted. This is the same idea that we used in LINECOMP to differentiate between line commands and macros. To illustrate this and other ways in which PREPROC processes macros and line commands, we will show the full version of PREPROC as it is implemented in the system kernel to date. There are some differences unrelated to the processing of macros, as well, but all will be explained in due time. PREPROC: SUBR(INLINE) ; CMDLINE: NEW PARSE (INLINE, '; NEW STRING(72); NEW INT; NEW STRING(10) 5 ARGLIST: NEW STRING(72); I: NEW INT; BPOS: NEW IN’ MSGOUT; WHILE (I = I + 1) LE AGGSIZE(CMDLINE) DO BEGIN BPOS = LOCSTR(' ',TEMPLINE = LBLANK(CMDLINE(I)|' ')); IF (CMD=SUBSTR(TEMPLINE ,1,BPOS-1)) EQ <'',' '> THEN BRANCH(LOOP) ; ARGLIST = SUBSTR(TEMPLINE , BPOS+1 , LENGTH (TEMPLINE))-BPOS) ; IF CMDTOKEN = MEMBER (CMD ,DOMCMDS) ‘THEN PROCCMD (CMD , CNDTOKEN , ARGLIST) ELSE IF MEMBER(CMD ,DOMMCL) THEN PROCCMD(CMD,1,ARGLIST) ELSE BEGIN MSGOUT(' INVALID COMMAND/MACRO' ,'>>> ' |TENPLINE); BRANCH (LOOP) ; END; END; END. In comparing this version with the simpler version shown in the first chapter, we can see that this is more complex and involved. First of all, the changes in the very first line are significant. The "PARSE" utility routine (that is, PARSE is loaded with the other utility subroutines during execution of SYSIPL), splits up a cher- DESIGN/AML, MACRO DEFINITION AND MACRO EXECUTION 41IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* acter string into an aggregate of strings according to a specific delimiting character. This delimiting character is often called a command separator, which in this case is the semi-colon ";". For example the following string 'abc;def' would be split up into a two element aggregate <'abc','def'>. The PARSE routine looks as follows: PARSE: SUBR(STR,DELINCHARS) ; DELIMS: NEW sINDEX (STR, DELIMCHARS )##<-1>; I: NEW 1; IF DELIMS(3) + 1 THEN RETURN(WHILE DELIMS(I = I + 1) +1 DO COLLECT SUBSTR(STR,DELIMS(I-1)+1, DELINS (I) -DELIMS (1-1) -1)) ELSE RETURN(); END; We use the command delimiter to split up the input line into what is called a command string or stream, in which a number of commands may be entered on the same input line all of which are separated from each other by the command delimiter. An example would be the following command sequence which is read all at once by READCMD: DOWN 4;D0 3; DOWN 1; DO * ‘This command string will (in the CON domain) skip 4 lines, execute the next 3, skip a line and execute the rest of the program from there, Such command streams are natural, during the process of de- veloping programs and PREPROC has been designed to support them. Continuing with our discussion of PREPROG, then, we see that CMDLINE is an aggregate representing one input line but with a number of commands or macros that may be represented on that one input line. For instance, CMDLINE for the above command string would look as follows after being generated: <'DOWN 4", "DO 3", DOWN 1',' DO #'> ‘Thus, CMDLINE is a four element aggregate where each element represents a unique command or macro (with its associated arguments) to be Processed by PREPROC. Thus we must iterate through PREPROC the same number of times as there are elements in the CMDLINE aggregate. The next few statements in PREPROC, initialize important variables. The iteration that we just indicated is processed by the "WHILE" loop which as we see runs through the number of times specified by the aggregate size of CMDLINE. The index variable in this case, is I which serves two purposes: first to keep a count of the number of times the WHILE loop has iterated, and second, to indicate which command is the one to be processed in CMDLINE. Thus when I is 1, then the first element of CMDLINE is to be processed, all the way up to when I is equal to AGGSIZE(CMDLINE) when the last command of 42 RPD: System ManualIBM INTERNAL USE ONLY - DRAFT *#* DO NOT COPY ** CNDLINE is processed. Thus within the loop, we do the same kinds of things that we did in the simpler version of PREPROC (generating AR- GLIST, CMDTOKEN, CMD etc.) except that we've generalized it to CMDLINE(I) instead of just CMDLINE. There is one more difference that has portent regarding macros: that involves the search for CMD among DOMCMDS and DOMNCL. Explananation is obviously due here. Searching for CMD among DOMCMDS is equivalent to finding out if the command is a valid line command. If so then the appropriate value of CMDIOKEN is generated and PROGCMD is called. Otherwise, the search returns a zero and we then search another file called DOMMCL that contains, of course a dictionary of all the valid macros that can be called within the context of that domain. DOMMCL has properties very similar to DOMCMDS, namely it is an aggregate of strings and is loaded along with the appropriate domain IPL file as in CONIPL for the CON domain. One note though...conceptually, DOMMCL is more dynamic than DOMCMDS. That is, DOMCMD is pretty much static unless a whole new command is created along with the corresponding command execution File, of course. DOMMCL, however, may be modified as macros are ad- ded or deleted to the system. These macro dictionary editing features have not been incorporated into the system although their implementation would be quite simple. If a match is found with DOMNCL, just as if a match were to be found with DOMCMDS, then that means that that element of the command string is a valid macro. To indicate this, CMDTOKEN is sent to PROCCMD as a 1. That is why the very first element of DOMCMDS is the string ‘scorn! because if this string was a valid command, then ‘the PROCCMD would be confused about whether the input was a line command or a macro. Note: the author has determined that '' (the null string) would be a better first element of DOMCMDS since this string can never be sent by READCMD to PREPROC. The first element of DOMCMDS would prevent system failure in the rare case that a demonic user enters a ‘as what he things is @ command. Of course, if the input is neither to be found in DOMMCL or in DOMCMDS, then it is, of course, a user error and the appropriate measures are taken. Now that we have determined what PREPROG looks like in its final version, let us take a closer look at the final link in the DESIGN/AML puzzle which is that of PROCCMD. Now that PROCCMD has been duly informed by PREPROC as to the nature of the user input, how does it execute the will of the user? ‘The case of line commands has been shown in chapter 1; for macros it is a slightly different story. The process to be taken is to load the object file corresponding to the macro that was invoked. Remem- bering that a macro is, in effect, an AML subroutine (or at least DESIGN/AML, MACRO DEFINITION AND MACRO EXECUTION 43IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** the object version of the macro is an AML subroutine), then all we have to do is execute this subroutine (mich in the manner of the conmand execution file) and then subsequently unload it in order to clear the computer's memory. A couple notes regarding theory, however: the user is not generally aware of the existence of the macro object file. In fact, the macro definition domain, in reality, creates two files during its opera- tion, that of the source file and the object file for the particular macro. Theoretically, speaking each domain is defined determinis- tically, in that each domain generates only one unique file which is @ member of that domains corresponding file group ( a set of files native to a particular domain which are created by that domain). This, in fact, is true, since to the USER there is only one file created because he has no concern with and cannot access the object macro file. This object macro file is always names by the following convention: Rnacro, that is an "R" is concatenated to the front of the name of the macro. The name of the macro is, of course, the name that is in the DOMMCL macro dictionary and is also the same name as the AML subroutine that was defined by the user in the macro definition domain. All this aside, let us now look at PROCCMD and its operational characteristics in detai: PROCCMD: SUBR (CMD, CMDTOKEN, ARGLIST) ; FN: NEW STRING(8) ; CLEANUP" PROCCIN") ; IF 1 = CHDTOKEN ‘THEN LOAD (FN = DOMFILES (CMDTOKEN) ) ELSE LOAD('R" |FN = CMD: EVAL(EN) 5 RETURN; NBER: MSGOUT(' INVALID ARGUMENT" ,DOMCMDS(CMDTOKEN)|' ' | ARGLIST) ; BRANCH (LOOP) ; REER: — MSGOUT("ARGUMENT OUT OF —_RANGE' ,DOMCMDS (CMDTOKEN) | ' "|ARGLIST) ; BRANCH (LOOP) ; PROCCLN: SUBR; UNLOAD(FN) 5 END; END; ‘Thus, PROCCMD checks to see if the input line is either a line command or a macro. It does not have to check the respective diction- aries because this has already been done by PREPROC. Rather, it 44 RPIIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** checks to see if CMDTOKEN is 1. If so, a macro is executed through the statement LOAD('R" [EN = CMD); As you can see, the convention of including an R before the macro object file is observed. Incidentally, this R is generated by the compilation process and is not seen by the user as mentioned before. ‘The NEER and REER labels refer to global error conditions that may occur at any time during the execution of line commands. Thus, a branch to NEER or REER during execution of a command execution file means that an error has been encountered and the necessary error recovery procedures taken. We have described in detail the processing of macros by the system. To summarize we can say that there are two considerations that mst be accounted for in processing macros. First of all, there is the problen of interpretation. That is, how is a macro recognized and how is the object file for that macro retrieved from the disk? We solved this problem through modifications to PREPROC and PROGCMD. In PREPROG we made sure that we resolved the differentiation between domain line conmands and macros through two different dictionary searches of DOMCMDS and DOMMCL respectively. In this scheme, line conmands take precedence over macros. But there is a command called MACRO which takes as an argument a macro which may, in fact have the same name a domain command, but the case may arise where the user may wish to execute the macro instead of the domain command. To in a sense solidify our conceptions of domain conmands versus macros let us examine the command execution file for this MACRO conmand. Remembering, of course, that the MACRO command is a standard domain conmand and not a macro; rather the arguments to MACRO represent the macro that the user wishes to execute. MACRO: SUBR; ‘TEMPLINE: NEW STRING(72); CMD: NEW STRING(10) ; BPOS: NEW LOCSTR('’' ,TEMPLINE = LBLANK(ARGLIST|' ')); IF (CHD=SUBSTR(TEMPLINE,1,BPOS-1)) EQ <'',' '> ‘THEN BEGIN MSGOUT('MISSING ARGUMENT TO MACRO INVOKER"); BRANCH (LOOP) ; END; IF MEMBER (CMD, DOMMCL) THEN PROCCMD (CMD, 1, SUBSTR (TEMPLINE , BPOS+1, LENGTH (TEMPLINE) -BPOS)) ELSE MSGOUT(" INVALID MACRO/META-AML COMMAND’, ">>> ' |TEMPLINE) ; END; As you can see this is almost an exact replica of PREPROC except that it does not possess the capability of processing line commands; rather it is a PREPROC that is custom-made to process macros which DESIGN/AML, MACRO DEFINITION AND MACRO EXECUTION 45IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* are of course represented in the argument list to the MACRO command. Thus the command execution file extracts the command field (CMD) and the argument field for the macro (ARGLIST) from the argument list to the MACRO command. Of course, a check is made to see if an argument actually exists. Otherwise a search is performed over the macros defined in that domain (the DOMNCL dictionary) and PROCCMD called with the appropriate parameters if, indeed, it is determined that this macro is valid for that domain context. Also involved in the interpretation of macros is the extraction of the corresponding object file for that macro in order to execute it. As in the case of domain line commands where the command execution file is extracted, this task is done in PROCCMD. PROCCMD assumes that the name of the object file has a unique relationship with the name of the macro which is passed as an argument (CMD) to PROCCMD. PROCCMD then loads this file and executes the subroutine that comes with. The second consideration with macros is, of course, that of the execution of the macro. We said that this execution is controlled by a subroutine that is loaded with the macro object file. This subroutine is a valid one in terms of AML and is generated during compilation of the edited DESIGN/AML macro in the macro definition domain. Compilation is a process that produces an object file that can be executed by that AML interpreter. In particular, line commands, which are not directly recognizable by the AML interpreter, are translated into a call to PROCCMD which then executes the line command. The parameters to PROCCMD are computed during the compilation process. Incidentally, we can always call PROCCMD since it is resident in the system kernel which is always an integral part of the system. A final point is that macros will perform faster than interactive input because the READCMD phase and the PREPROC phase are skipped during interpretation of each line command. Our next goal in this implementation guide will be to discuss some of the other types of commands that can be processed by the system. Altogether, the diversity of command forms, gives the Robot Devel- opment System a high degree of flexibility and power. Let us see how this is done. 46 RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY * DESIGN/AML, MACRO DEFINITION AND MACRO EXECUTION 47IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* 48 RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** 5.0 IMMEDIATE COMMANDS AND PF KEY COMMANDS 5.1 INTRODUCTION In this last chapter, we demonstrated the interpretation and execution of macros, and in the process we described PREPROC and PROCCMD in their complete form as parts of the system kernel. In this chapter, we will complete the triad and describe READCND in its complete form as well in order to understand aspects of immediate and PF key commands In short, these three commands permit quicker execution and facilitate user-oriented domain architectures. 5.2 IMMEDIATE COMMANDS Immediate Commands allow the user to perform useful functions interactively and quickly. Immediate Commands may not be called from macros and are relevant only when the domain is operating interactively. This is primarily because the processing of immediate com mands occurs during execution of READCMD. As a result, it follows that an immediate conmand may be invoked in any domain regardless of the particular characteristics of the domain environment. In addition, immediate commands are not generally progranmable unless the system kernel (specifically READOMD) is modified to reflect the changes in the immediate commands. There are four immediate com mands, each of which are represented by one character. These are described below: § This command is the AML statement evaluation command. It allows the user to evaluate during interactive dialog with any domain an AML statement directly. The statement is itself the argument to the $ immediate command and follows the dollar sign on the input line. An example is : sats ‘The dollar sign must be the first character (other than a blank) that the user types on the input line. In other words, the § does not have to be on the very IMMEDIATE COMMANDS AND PF KEY COMMANDS 49IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** first character position on the line but rather the very first non-blank character on the input line. The result of this command in the example given would be to output the result on the message field on the sereen (lines 19 and 20). The result would look as follows: CON => AML STATEMENT EVALUATED 9 This immediate command also checks for errors in the AML statement and returns the appropriate message if an error is encountered. = This command repeats the execution of the last input line entered. There are no arguments to ‘this immediate command; the arguments are in a sense, implicitly defined as the last input line entered by the user interactively. However, the last input line is defined as the one that has a command or command string composed solely of a line commands or macros (or both). That means that immediate commands, full-screen commands , PF key commands and pendant commands are not repeated by the "=" immediate command, but rather the most immediately preceding command string containing line commands and macros is executed instead. If the last input line, we entered was as follows: FIND /SAMPLE STRING/ then typing in "=" after the FIND command completes execution will repeat the search for "SAMPLE STRING’. Furthermore, according to the rules we just stated, we could enter "=" as many times as possible because the last input line to be executed again would be the FIND conmand and not the preceding input line contain "=". ‘This command functions exactly the same as the "=" immediate command. 2 This immediate command is similar to the "=" conmand, in that it also retrieves that last input line containing a command string of line commands and macros. The difference, however, is that, instead of directly repeating the execution of the last input line, that line is re-displayed on the input line. Essentially the system will prefill the interactive input line allowing the user the edit the input line or change it entirely. 50 -RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT Copy ** For example, if we had entered that FIND command as we did in the last example, then typing in a "2" would display our input line as follows: > FIND /SAMPLE STRING/ exactly the same as we had entered it. We could then push the ENTER key which would merely repeat the execution of the input line or we could edit the input line...for example: C> FIND /SAMPLE STRING TWO/; and then push the ENTER key to proceed with the execution of this input line. We have described the functional characteristics of immediate commands and must now explain how these immediate commands are implemented (as we said before) in READCMD? As mentioned, we promised to show READCMD in its entirety, Well, in order, to explain immediate commands we will do just that: 5.3. IMMEDIATE COMMAND INTERPRETATION IN READCMD READCMD: SUBR; KEY(<113,114>4#(116+10TA(16)) ,'PNDHAND") ; KEY(<4,5,6,7>,'PFHAND' ); IP INMGMD BQ <'"","2",'=", "5 '> THEN <> ELSE OLDLINE = INLINE; REPEAT + BASIC READ LOOP BEGIN - | POINT(O,22)5 i 1 DISPLAY (DOMTOKEN| '>') ; ~~ | END - | UNTIL LENGTH (READ(O, INLINE); co v KEY (<4,5,6,7,113,114>#(116+I0TA(16)),'")5 PREFILL(''); IF CIMMCHD = SUBSTR(INLINE = LBLANK(INLINE),1,1)) EQ '$" THEN BEGIN OLDTRAP = ERRTRAP('EVALTRAP") ; NSGOUT('AML STATEMENT EVALUATED' ,EVAL(DROP(INLINE,1))); ERRTRAP (OLDTRAP) ; BRANCH (LOOP) ; END ELSE IF IMMOMD EQ <'"","="> THEN RETURN(OLDLINE) ELSE IF IMMCMD EQ '2" THEN BEGIN IMMEDIATE COMMANDS AND PF KEY COMMANDS 51IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** PREF ILL (OLDLINE) ; BRANCH (LOOP) ; END ELSE RETURN(INLINE) ; EVALTRAP: SUBR(EMN) ; MSGOUT('ERROR IN EVALUATING AML STATEMENT CVTNS(ENN) |": '|(STRING(65) IS MESSAGE (EMN))); PREFILL (INLINE) ; ERRTRAP(OLDTRAP) 5 BRANCH (LOOP) ; END; END; The first observation we make of this is that READCMD has increased almost three times in size from the simple read loop that we had used in our first discussion of the system kernel. But we can still see our read loop in intact form within the top half of the READCMD subroutine. The first differences we see though is the KEY statements surround- ing the read loop. They have to do with the processing of PF key and pendant key commands, but to summarize we should say that the first set of KEY statements enables the PF and pendant keys while the last set of KEY statements disables the PF and pendant keys. This just means that the system can receive commands in this form only the during the same time as regular line commands and macros may be re~ ceived. This ensures that a pendant command, for instance, will not be invoked during the execution of a line command, or any other command for that matter. ‘The next difference that we see is the IF statement directly preceding the read loop. This IF statement determines what OLDLINE will be. OLDLINE represents the last input line entered containing only Line commands or macros. Recall of course, that when we were discussing the command and the "?" commend we stipulated the restrictions on what the last line entered meant as far as these commands are concerned. Well, this IF statement resolves those sti- pulations by setting OLDLINE to the same as INLINE only if the first non-blank character in the directly preceding input line was NOT an immediate command. As you might guess, IMMCMD is the variable that holds the very first non-blank character in the directly preceding input line. For instance, if the last input line we entered con- sisted of the following: c — sTARTU TOP; DO 53 the IMMCMD would be set to 'S' and OLDLINE would be set to the input string as well. OLDLINE and IMMCMD, are variables that are initialized during the system IPL, process when the SYSIPL file is loaded and executed. 52 RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* The only other major difference in the READCMD subroutine from its earlier form is in the bottom half of the subroutine. This is where immediate commands are processed and executed. Let us go through the sequence of operations. The first task is to generate IMMCMD since this will be examined for the presence of any immediate commands. This is simple enough and is performed by the following statement (embedded in the IF statement that starts off the immediate command interpretation code): IMMCMD = SUBSTR(INLINE = LBLANK (INLINE) ,1,1) After IMMCMD has been extracted from the input line, it is checked for the presence of any immediate commands. The first of these is "s" which represents the immediate AML statement evaluation command. If, in fact, IMMCMD does indicate the immediate AML statement evaluation command, then a number of steps are taken. First of all, an error trap is set to the nested subroutine EVALTRAP. This subroutine is at the bottom of the READCMD subroutine. EVALYRAP is called when an error is encountered during at- tempted evaluation of the AML statement that was presented as an argument to the "§" immediate command. This ensures that the proper steps are taken for error recovery. The next step does the two fold job of evaluating the AML statement and displaying the result on the message field. This is done through a call to MSGOUT. We end this by setting ERRTRAP to OLDTRAP because the system may have already set an error trap subroutine depending on what domain is currently operating (it is hoped that a generalized system error trap subroutine would be incorporated in the system kernel so that AML errors that somehow got tripped would not have adverse effects on the oper- ation of the system kernel and that recovery would be graceful enough so that the user can still enter commands without getting involved with the AML system at the level of the AML interpreter. ‘The EVALTRAP subroutine works by also calling MSGOUT, but instead of sending the results of the aborted evaluation of the AML statement, an error message with the offending immediate command argument would be displayed. In addition, the editor may then edit the statement he just entered because upon returning control to the read loop, EVALTRAP prefills the input line with the immediate command and the erroneous AML statement. The next immediate command to consider is the "=" command which has as a synonym the character """ (standing for ditto). Execution of this command is as simple as returning OLDLINE to PREPROC so that OLDLINE will be processed, instead of the current input line which of course contains the = or the " immediate command. Finally, the ? immediate command is executed by prefilling the input line with OLDLINE. Note... the author has determined that the code IMMEDIATE COMMANDS AND PF KEY COMMANDS 53IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY #* for the ? immediate command should look as follows with the elimi- nation of the redundant branch to loop: ELSE IF IMMCMD EQ '?" ‘THEN PREFILL(OLDLINE) ELSE RETURN( INLINE) ; The last ELSE condition, is the case when there are no immediate conmands and the current input line is returned to PREPROG. This is the case that was coded for in the earlier edition of READCMD. 5.4 PF KEY COMMANDS Now that we have finished our discussion of immediate commands, we will continue with a description of the implementation of PF key commands. These commands are interactive in nature. That is, they can only be entered by the user when the system is awaiting interac~ tive input (when READCMD is iterating through the basic read loop). That means that PF key commands cannot be directly invoked through a macro; they may be indirectly invoked. We shall see how this apparent paradox is resolved. First of all, what is a PF key command? Basically, a PF (or Program Function) key is a programmable button on the keyboard that the user pushes whenever he wishes the system to do the things that the PF key is defined to do. In this system, most domains will have the capability of PF key functions (this excludes full-screen editors since they have built in functions defined for the PF keys, as we will discuss later). Can these PF keys do anything and everything? The answer is both No and Yes. No because the only functions defined for the PF keys are either line conmands or macros. The PF keys can do anything and everything because, we can program our mac~ ros to do these things. ‘Therefore what pushing a PF key entails is that the line command or macro defined for that PF key will be executed in the place of actually typing in and entering that line command or macro in the input line. It is obvious, therefore, that only single commands or macros could be defined for a PF key and not a command string although a macro could, of course, code for a command string. ‘The most obvious advantages of using PF keys is that they speed up and facilitate the user interaction with the system because a lesser number of keys have to be pressed when PF keys are used effectively. The other advantage, that is part of the implementation of PF key commands, is that line commands or macros invoked through PF keys actually will run faster than line commands and macros that are keyed into the input line and entered in that manner, 54 RPD: System ManualIBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** If you look back at the complete version of READCMD that we discussed earlier, you will see that the KEY statements define keys 4,5,6,and 7 to be ascribed to the subroutine PFHAND. This assignment between these PF keys and this subroutine enables the 4 PF keys during the duration of the read loop. Thus, if the user pushes a PF key during this time, PFHAND will be called. There is a separate PFHAND for each domain. This means that PFHAND is loaded during the IPL process for the domain. In the case of the GON domain, CPFHAND would be loaded during execution of the CONIPL file. CPFHAND contains the PFHAND subroutine that is specific to the CON domain. One particular reason for the specificity of PFHAND when, indeed, it is possible to implement it in a generic sense for all the domains in the system is that a specific PFHAND would run faster than a generic one, a major consideration in the implementa tion of PF key commands. Let us take a look at PFHAND; the details of its operations are cru- cial to understanding the implementation of PF key commands. PFHAND: SUBR(KN) ; KEY (3+10TA(4),' PREFILL('')5 PROCCMD (CONPF'S (KN=3) ,''); BRANCH (LOOP) ; END; Note: this code is slightly different than the one that is currently implemented. The author believes that the old version has been ren- dered obsolete by a number of changes in the system during its development and that the old version (the one on the diskette) may not, in fact, work properly. The first thing that we do upon invoking PFKAND (remember that PFHAND is called when a PF key 4,5,6 or 7 is pressed) is to Prefill the input buffer with a null string. This step takes care of the case in which the user types a line on the input field but then presses a PF key without pressing the ENTER key. This ensures that the next time around the system kernel, that is when the read loop is entered again, a thoroughly clear input field will be presented to the user. ‘The next step is an important one because it disables the PF keys. Just as it is inadmissible that a PF key be processed during the concurrent processing of another command, the case when a PF key is pressed during the execution of a PF key command must also be accounted for. This statement prevents the system from blowing up if this takes place. IMMEDIATE COMMANDS AND PF KEY COMMANDS 55IBM INTERNAL USE ONLY - DRAFT ** DO NOT COPY ** The next step is the one that actually interprets ‘the command defined for the PF key that was just pushed. The problem of interpretation is two fold. First of all, it involves finding out what the line command or macro defined for that PF key actually is Secondly, that line command or macro must then be executed. The second problem can be solved easily enough by a call to PROCCND. Recall, of course, that PROCCMD is responsible for the execution of any line command or macro. Thus when we hear the phrase "execution of any line command or macro", we should naturally think of PROCCMD as the solution to the problem. Since we call PROCCMD directly we speed up the interpretation of PF commands because we skip any code involved with interpreting immediate commands in READCMD or other commands in PREPROC. The first part of the problem of interpreting PF key commands, name ly that of finding an association between the PF key and some line command or macro for which it was defined is a little bit trickier. We know that the information necessary to establish this association must be the same information that is sent to PROCCMD. That is we must some how compute the values for CHD (the conmand field) and CHDTOKEN. ARGLIST can, of course, be omitted because PF key commands do not carry any implicit arguments for the functions for which they are defined. To do this we create a data structure which we call CONPFS in the case of the CON domain. CONPFS is an aggregate of four elements and is loaded during the execution of the domain IPL file. Each of these elements contains information that points to a specific line command or macro in the line conmand/macro repertoire for that domain. In particular, since there are four programmable PF keys, there are four elements to the CONPFS aggregate, the first one corresponding to the first PF key and so on. Each element of CONPFS is in itself an aggregate of two elements: the first one being the name of the command or macro (corresponding to the CMD (command field) that is generated in PREPROC and also sent to PROGCMD), and second element being equivalent to CMDTOKEN Which refers to the index of the command execution file among the dictionary of command execution files contained in DOMFILES. Of course, if the PF key invokes a macro then this second element of the aggregate will be a 1 just as in the case of macro processing in PREPROC. Thus, CONPFS contains the information necessary to pass onto PROCCMD which is then able to execute the line command or macro specified by that PF key 56 RPD: System Manual

RPD System I

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

RPD System I

Uploaded by

Copyright:

Available Formats

You might also like