Hall of Fame

home *** CD-ROM | disk | FTP | other *** search

/ Hall of Fame / HallofFameCDROM.cdr / util1 / incx100b.lzh / INC-PROG.LZH / HELP.LZH / MCAEL.HLP < prev next >

Wrap

Text File | 1991-02-28 | 38KB | 666 lines

mcael Help information about: InContext Procedure Language E╔════════════════════════════════════════════════╗ E║ CInContext Procedure LanguageE ║ E╚════════════════════════════════════════════════╝ CA Word to the Wise... If you can write MS-DOS batch procedures, you should have no difficulty learning to use the InContext Procedure Language. If "batch files" are beyond your present capability, though, then you may want to learn about them before you undertake to write your own InContext procedures. You should find the information you need in your MS-DOS User Guide. The procedures you write here will usually be based on MS-DOS commands, with some notable assistance from a few special commands made available by InContext. Programming, particularly of the "batch file" sort, is really not very difficult, and there's no reason to be intimidated by it. It should not be done carelessly, though, since it is possible to inadvertently modify, or even delete, files. Current backups of your files can be a real lifesaver, whether you're testing out new procedures or not, but they're especially wise in such a case. You may find it helpful to F ªPDrint B this information, for easy reference. CHow InContext Procedures Work A CprocedureB is a list of commands that are executed when: ZmcaB CB an CactionB is selected (see CJ Actions CB). ZmcdB CB an item from the CdoB list is selected (see CJ The Do Command CB). The CcommandsB in a procedure consist of some mixture of CMS-DOS commands and Cinternal InContext commandsB. You are assumed to be familiar with the common MS-DOS commands, such as "echo", "copy", "move", etc., and we will also refer to the invocation of other programs as a use of "MS-DOS commands", since they are invoked by asking MS-DOS to execute them. Obviously, though, the InContext commands are unfamiliar, and they will be discussed in detail below. When a procedure is executed, the commands are executed in sequence, starting at the top (except as this may be altered by MS-DOS CgotoB, and InContext CmenuB and CforEachObjectB commands). The internal commands are simply executed by InContext when it reaches them. MS-DOS commands have to be passed to the MS-DOS command processor, though. (Normally, this is the program "command.com", but some users substitute an alternative command processor.) If several consecutive lines of a procedure are MS-DOS commands, they are passed to the command processor by writing them out as an MS-DOS batch file and arranging for the command interpreter to execute the batch file. If an MS-DOS command occurs alone in a procedure, or is surrounded by internal commands, it is passed directly to the command processor without being written to a batch file. Since there is some overhead associated with invoking the command processor, you can see that CunnecessaryB alternation between MS-DOS commands and internal commands would impede performance. If an error occurs during execution of a procedure, InContext will display the error message and halt execution of the procedure. Please note that InContext has no direct way of knowing about errors that may have occurred during the execution of other programs (command.com does not return the ERRORLEVEL value that is available for testing within batch files). The only errors that can be directly detected by InContext are errors in the execution of its internal commands. For this reason, if for no other, you should probably use the CinternalB versions of such commands as copy, delete, etc. CSwapping InContext Out of Main Memory Whenever the MS-DOS command processor is invoked to execute an MS-DOS command or another program, part of the InContext program and data are "swapped out". That is, a portion of InContext is written out to either EMS memory or to disk, in order to make room for the (possibly large) program that is being invoked. You can control how this swapping occurs, and how much memory is freed. This is done globally by setting the ZmcmoeB appropriate configuration options (see CJ MS-DOS Command Execution CB), and locally by the CmemoryB command (see below). CA Small Example The following example is a little contrived, for which we apologize. Most actions require only a one-line procedure, and we need an example here that will illustrate a bit more than those actions would allow. Let's suppose that you have a spelling-checker program called "spellit", which scans an ASCII text file, noticing words that don't match any entry in the program's dictionary. Assume that the program prompts the user for corrections in such a case, and rewrites the file, with spelling corrections, on exit. Let's suppose that it also updates its own dictionary if you give it new words during an execution, and that the dictionary is kept in the directory "c:\mystuff". Finally, let's assume that spellit requires no more than 256K (256 kilobytes of main memory) to run. If we would like to add a "spell-chk" action for objects of the "txt" class. An acceptable procedure for such an action might be simply spellit %f where the characters "%f" will be replaced by the filename of the selected text object. A more complete procedure, though, might be !memory 256 spellit %f !relogDir c:\mystuff This procedure illustrates the use of both internal commands and MS-DOS commands. The commands preceded by exclamation points (C!B) are internal InContext commands. The first command ("!memory 256") directs InContext to swap out only enough of itself to provide 256K of memory for the following MS-DOS process. The second command ("spellit %f") executes spellit on the selected object. The third ("!relogDir c:\mystuff") causes InContext to update its record of the contents of the directory c:\mystuff, so that it will reflect the modified size, date, etc. of the dictionary file. CVariable Substitution One thing you need to know more about is variable substitution. During the execution of procedures, InContext looks for a set of one-character "variable names", each of which is preceded by the percent (C%B) character. Whenever one of these variable names is encountered, it is replaced by an appropriate value before the command is executed. For example, if the currently selected object is "mystuff.txt", then the command myeditor %f becomes myeditor mystuff.txt before it is passed to MS-DOS for execution. The InContext variables are: C%cB The CclassB of the currently selected object C%dB The full pathname of the currently selected Cdirectory C%DB The current Cdate C%fB The CfilenameB of the currently selected object C%hB The Cfull pathnameB of the currently selected object C%kB The name of the currently selected CtaskB C%KB The CdescriptionB of the currently selected task C%lB The number of ClinesB currently on the video display C%mB For use only in the group action list, the CmultipleB filespec that describes the currently displayed objects. This might be replaced by "*.*", if the "ALL" view is selected, or by "*.txt", if only the text class is selected, or by "*.doc *.txt" if a view containing both "doc" and "txt" classes is selected. C%pB The filename CprefixB of the currently selected object C%TB The current Ctime C%uB The name of the current CuserB of InContext The following additional variables are related to the "query" command. C%1B The current value of variable 1 C%2B The current value of variable 2 C%3B The current value of variable 3 C%4B The current value of variable 4 C%5B The current value of variable 5 C%6B The current value of variable 6 C%7B The current value of variable 7 C%8B The current value of variable 8 C%9B The current value of variable 9 The following additional variables have meaning only when executing a "forEachObject" loop: C%CB The class of the current object C%FB The filename of the current object C%HB The full pathname of the current object C%PB The filename prefix of the current object CMacros The use of Macros is common in programming languages at all levels, and it can greatly increase power and reuseability of procedures. For ZmcaemB information, see CJ Macro Action Definitions CB), Macros in procedures are indicated by the use of the pound sign (C#B) as the first character of the line. Thus, a common way of invoking the user's preferred text editor is #editText where the "editText" macro contains the detailed command(s) necessary to invoke the editor in the desired manner. CInContext Internal Commands The internal commands are listed below, along with descriptions and, where appropriate, examples. For any commands that take arguments, the syntax of the command is also shown. In syntax descriptions, everything shown in CboldB text must appear as shown, while everything shown in ordinary text is a placeholder. Optional information is surrounded by square brackets. Thus, the description: CdeleteB [ filename ] [ CnoqueryB ] indicates that the delete command takes two optional arguments, one of which is a filename and the other of which is the string "noquery". The internal commands you would ordinarily use are: CchangeDirB This command changes the current working directory to a specified directory. The chosen directory will remain the current working directory until the next "changeDir" command, or the next MS-DOS "cd" command, or the end of the procedure. This command is equivalent to the MS-DOS "cd" command except that it can cause a change in drive, as well as directory. Syntax is: CchangeDirB pathOfNewDir Thus, to change to the "temp" directory on the "d:" drive, the command would be changeDir d:\temp Use of this command is preferable to the MS-DOS "cd" command, because InContext will be aware of the working directory, and will therefore automatically relog the directory. CchoiceB See "menu". CcopyB This command exhibits two different kinds of behavior, depending on the arguments used. Syntax is: CcopyB [ source destination [ CnoqueryB ] ] If no arguments are used, as in copy the command prompts the user for the name (or possibly directory or full path) to which the selected object should be copied. If the user responds with such a name or path, the copy operation is executed. Alternatively, if source and destination pathnames are given, the indicated source file is copied to the indicated destination. The source must indicate an existing file, and may be a simple filename, if the file is in the current directory, or a complete pathname. The destination can be a simple filename or a full pathname. If the destination is found to be a directory, a new copy of the source will be placed in the destination directory, using the source filename. Otherwise, a new copy of the source file will be created and given the destination filename. If there is already a file using the destination name, the user will be asked for permission before copying occurs, unless the "noquery" argument is present. Thus, the command copy myfile.txt a:\ noquery would copy "myfile.txt" to the root directory of the A: drive, and would not ask permission before over- writing a file of the same name there. CcreateObjectB This command creates a new object, based on the filename prefix and class specified in the command. Syntax is: CcreateObjectB prefix class Thus, the command "createObject mynext doc" would create the object "mynext.doc" in the current directory. CdeleteB This command deletes the specified object, or if none is specified, deletes the currently selected object. The user is asked for permission before deletion, unless "noquery" is specified. Syntax is: CdeleteB [ filename ] [ CnoqueryB ] Thus, to delete the file "mytemp.txt", without asking user permission, the command would be delete mytemp.txt noquery If the file does not exist, no deletion occurs and no error is noted. CeditB This command invokes the internal editor on the specified file, if any, or on the currently selected object, if no file was specified. Syntax is: CeditB [ filename ] CeditDictionaryB Some of the files used by InContext are "dictionary" files (class "dic"). The internal dictionary editor is made available for use on such objects by this command. You might use this command to create dictionary files for use with the "info" command (see below). Syntax is: CeditDictionaryB [ filename ] CendForB See "forEachObject". CendMenuB See "menu". CforEachObjectB This command allows you to execute a portion of a procedure once for each object currently being displayed. You might use it if you have a program that only operates on one file at a time, but you want to be able to invoke it on a whole class or view. If the program is question is "theprog", the commands required would be: !forEachObject theprog %F !endFor Notice that the "endFor" command is also required, and that it indicates the end of the loop that will be executed once for each object. Notice also that the special variable names %F, %H, %C, and %P must be used instead of %f, %h, %c, and %p. CinfoB This command allows you to display a scrollable window containing text you have written. It is useful for providing explanations of a procedure during its execution. Syntax is: CinfoB dictionaryPath term [ title ] The information displayed will be the definition of the specified term, taken from the dictionary ("dic" object) whose full MS-DOS pathname is specified. If you provide a title, that title will be displayed, as well. For example, to display information at the beginning of a Do procedure that downloads stock prices, you might use the command: info c:\incontxt\myinfo.dic getprice CkeyStuffB This command allows you to place information in the keyboard buffer before calling an application. Suppose, for example, you have a word processor that doesn't allow you to specify a filename on the command line, but expects you to select a "file load" command after you're in the program. You might use a command sequence like: !keyStuff "FL%f\EN" myWordProc to cause it to automatically load the selected object upon entry. The !keyStuff command loads the keyboard buffer with the command characters 'F' and 'L', followed by the filename of the currently selected object, followed by the ENTER key. Those characters will then be read by the program "myWordProc" as if they had been typed from the keyboard after the program was invoked. This will not work with ALL programs, but works with most. This feature greatly increases your ability to "encapsulate" applications with InContext. There are a number of special characters that can be loaded into the keyboard buffer using this technique. An example is the ENTER key designated by the "\EN" in the example above. These special characters are all indicated by a backslash and a two-character code that represents the special character. The codes are as follows: For Cfunction keysB, the code consists of the character "F", followed by a numeric digit from 1 through 0. These correspond to function keys F1 through F10. "\FA" also means F10, and "FB" and "FC" correspond to F11 and F12 on the extended keyboard. (The hexadecimal symbols for 10, 11, and 12 are A, B, and C, respectively.) If Cshifted function keysB are desired, the codes are "\S1" through "\S0" and "\SA" through "\SC". CControl-function-keyB combinations are obtained by "\C1" through "C0" and "\CA" through "\CC". CAlt-function-keyB combinations are "\A1" through "\A0" and "\AA" through "\AC". Ordinary Ccontrol charactersB, such as control-A, use codes beginning with '^'. Thus, "\^A" through "\^Z" mean control-A through control-Z, and control-key versions of the following additional characters can be created this way: [ \ ] ^ _ @ Ordinary Calt-key charactersB, such as alt-A, use codes beginning with '@'. Thus, "\@A" through "\@Z" mean alt-A through alt-Z, and alt-key versions of the following additional characters can be created this way: numeric digits, -, = All remaining Cspecial charactersB are shown in the following table: LA left arrow LC control left arrow RA right arrow RC control right arrow UA up arrow UC control up arrow DA down arrow DC control down arrow HM home HC control home ED end EC control end PU page up QU control page up PD page down QD control page down IN insert DE delete G+ grey + G- grey - G* grey * PS PrtSc PC control PrtSc TA tab BT back tab ES escape BS back space EN ENTER (carriage return) LF line feed N0 numeric key-pad 0 N1 numeric key-pad 1 N2 numeric key-pad 2 N3 numeric key-pad 3 N4 numeric key-pad 4 N5 numeric key-pad 5 N6 numeric key-pad 6 N7 numeric key-pad 7 N8 numeric key-pad 8 N9 numeric key-pad 9 N. numeric key-pad . N+ numeric key-pad + N- numeric key-pad - N* numeric key-pad * To stuff the backslash character into the buffer, use two backslashes in succession, as "\\". In the current version of InContext, the string that is loaded by "!keyStuff" is restricted to 15 characters. This will be extended in a later version. Incidentally, whenever InContext executes another program, it clears the keyboard buffer on return. This prevents unprocessed keystrokes from doing unexpected things upon return to InContext. However, if the "!keyStuff" command is used and not followed by the execution of another program, the keystrokes are left in the buffer and read by InContext as if you had typed them in yourself. This allows you to define procedures that exert user-level control over InContext, if you like. This is recommended for knowledgable users only. An especially useful application of the latter is in an InContext startup ("incStart") macro. By placing in that macro, for example, !keyStuff "df" it is possible to cause the automatic execution of a Do procedure (e.g., "fontset") at InContext initialization time. CmemoryB This command allows you to specify the amount of memory needed for the next following block of MS-DOS commands. You can optimize InContext performance by requesting only what is actually needed, if you choose to do so. Syntax is: CmemoryB kilobytes Thus, to invoke a simple word-count program that needs only 64K of memory, you might use the commands !memory 64 wc %f CmenuB This command allows you to construct menus within a procedure. Syntax is: CmenuB [ title ] This command is used with a series of "choice" commands and an "endMenu" command, to specify a whole menu and the consequences of each possible choice. A simple example is: !menu "Do which simple MS-DOS operation?" !choice "Check disk" chkdsk !choice "Show directory contents" dir !endMenu Menus may not be nested (but notice that that probably isn't necessary, given that the menus occur in the context of actions that are themselves menu- selected). CnoRelogB This command can be used to slightly speed up the return of InContext after a procedure, if you know that the procedure cannot alter any files. By letting InContext know that the files cannot be altered, you eliminate the need for relogging the files in the current directory upon return from the procedure. This command can occur anywhere in the procedure. A common example would be the use of a viewer: !noRelog pcxview %f CpauseB This command causes InContext to pause, and wait for a keystroke or mouse key depression. It is used immediately after a DOS command or external program in order to allow the user to look at the results of that operation before returning to InContext. CqueryB This command allows you to ask the user for information, and then to use the information in subsequent commands in the procedure. Syntax is: CqueryB variable question length InContext provides nine variables whose values can be set by query commands. The first argument is the number of the variable that will contain the user's answer. The second argument is the text of a question that will be asked. The third argument is the length, in characters, of the answer field. At the risk of waxing a little fanciful, suppose you have a program, "coatarms" that displays a coat of arms for the user's family, given his family name. You might write: !query 3 "Enter your last name" 20 coatarms %3 If the user answers "Smith", this would result in the actual execution of the command "coatarms Smith". CrelogDirB Unless you use the "noRelog" command, InContext always checks all the files in the current directory at the end of each procedure, to make sure that its object list is up-do-date. It does CnotB automatically relog other directories, however. If you execute a program that is known to modify the contents of some other directory, you can cause InContext to update the log for that directory as well, by use of the "relogDir" command. Syntax is: CrelogDirB pathOfDirectory For example, if your editor automatically backs up all files to the directory "c:\backup", and you want the object list to be current whenever you go to that directory, you might use the sequence myeditor %f !relogDir c:\backup to invoke your editor. CrenameB This command exhibits two different kinds of behavior, depending on the arguments used. Syntax is: CrenameB [ source destination [ CnoqueryB ] ] If no arguments are used, as in rename the command prompts the user for the new name for the selected object. This may be a simple filename or a full pathname (this command can be used to move the selected object to another directory, or even another drive). If the user responds with such a name, the object is moved and/or renamed, as appropriate. Alternatively, if source and destination pathnames are given, the indicated source file is moved to the indicated destination. The source must indicate an existing file, and may be a simple filename, if the file is in the current directory, or a complete pathname. The destination can be a simple filename or a full pathname. If the destination is found to be a directory, the source object will be placed in the destination directory, using the source filename. Otherwise, the source object will be given the destination filename, and moved to the indicated drive or directory if that information was included in the destination. If there is already a file using the destination name, the user will be asked for permission before renaming occurs, unless the "noquery" argument is present. Thus, the command rename myfile.txt a:\ noquery would move "myfile.txt" to the root directory of the A: drive, and would not ask permission before over- writing a file of the same name there. CresetMouseB Some programs which you may invoke from within InContext disable the mouse and fail to restore it upon exit. If you don't see a cursor upon return from such a program, or if the mouse no longer works, you should add the "resetMouse" command to the procedure. On some machines, the mouse reset operation adds a second or two to the time required to return to InContext; that's why it isn't done every time. CunloadB A few memory-hungry applications may require more memory for their execution than InContext can make available by swapping itself to disk or EMS. A good example is Ventura Publisher, if run on a machine that doesn't have EMS memory. The "unload" command can be used to cause InContext to write out the desired MS-DOS commands to a batch file, and then Cquit altogetherB, freeing CallB of the memory used by InContext. Since the batch file is still there, it can be executed from DOS. When you installed InContext, you installed a batch file, "inc.bat", which is used to execute InContext. "inc.bat" checks, after each invocation of InContext, to see if a procedure batch file has been left behind for execution. If so, that batch file is executed and InContext is reloaded. You will only want to "unload" InContext in those few cases that really need it, for performance reasons. Note that, when "unload" is used, only the block of MS-DOS commands immediately CfollowingB "unload" can be executed. If you have any additional internal commands after that block, they will not be executed. CverifyB This command asks the user if it's OK to proceed, and terminates the procedure if the user fails to answer "Yes". Syntax is: CverifyB [ question ] If a question is specified, it is asked instead of the default question. Thus, a possible form of this command is verify "Is it OK to archive this file?" CviewB This command invokes the internal viewer on the specified file, if any, or on the currently selected object, if no file was specified. Syntax is: CviewB [ filename ] CviewLZHB This command invokes the internal LHARC viewer on the specified file, if any, or on the currently selected object, if no file was specified. Syntax is: CviewLZHB [ filename ] The following commands are also available, but you will ordinarily have no need to use them in your own procedures: CdeleteDirB If the current directory is empty and is not the root directory of its drive, this command deletes the directory and moves to the next directory above it. CdeleteGroupB This command checks with the user first, and then deletes each currently displayed object. Depending on the user's choice, the objects can be deleted or saved individually, or deleted as a group in a single operation, or the command can be aborted. CputB This command drops either a copy or the original of an object being "carried" into the current directory. The user is asked which is preferred. This command is really only intended for internal InContext use. CtakeB This command causes InContext to "pick up" the selected object, for possible later copying or moving via the "put" command, above.