# HELPCL1 - HELP WITH INFO ON CLONE LANGUAGE # LAST EDIT: 13-OCT-81 CMD='?' LITERAL .TEXT .REPEAT ( .IF CMD$='?' ( CLONE statement components are: ASK or REQUEST BEGIN or ( BREAK CALL or macro name alone @file name (type AT) DISABLE DO ENABLE END or ) FOR GET or [expression] IF q THEN s1 ELSE s2 LITERAL, CLONE LOG, NOLOG LOOP MCR PASS n or @ n PRINT REPEAT REPLY RESUME RETURN RUN STACK STOP SUSPEND SYS TEXT, NOTEXT TRACE, NOTRACE UNLESS q THEN s1 ELSE s2 UPDATE EXPRESSIONS CONSOLE COMMANDS . ) .CMD=ASK 'TYPE COMMAND NAME, ? FOR LIST OR CR TO EXIT ? ' .IF CMD$='' (NOTEXT RETURN) .IF CMD$='?' LOOP .IF CMD=='ASK' ^ CMD=='REQUEST' ( ASK and ASKN: The ASK statement asks a question at the terminal and returns the result to a CLONE macro. The resulting value may be used for computation within the macro or may be REPLIED to a program. ex. A=ASK 'prompt string' The value assigned to A is a text string read to end of line. The ASK command does not perform any checking or type conversion. To input a numeric value use ASKN ex. I=ASKN 'PLANE NUMBER ? ' In this case the value must be an integer numeric value. For either input request the prompt may be an expression enabling the prompt string to be composed at run-time. REQUEST is provided as a synonym of ASK. .LOOP ) .IF CMD=='BEGIN' ^ CMD=='(' ( BEGIN OR (: Define the beginning of a BLOCK. All statements upto END or ) compose a single compound statement. Blocks Are generaly VOID but may be NON-VOID. A VOID block has no value itself and any statement which has value within a void block (the literal 5 for instance) is treated as a REPLY statement. A NON-VOID block is created by using a block within an expression ex. A=(.........) This form is well known in arithmetic expressions however such a NON-VOID block may contain multiple statements one of which must be the block value. ex. A=(B=6 2*B) There are no constraints on the position of the valued statement but there must only be one such within a NON-VOID block. .LOOP ) .IF CMD=='BREAK' ( BREAK: Within any loop construction BREAK causes an immediate exit from the loop. Execution continued at the statement immediatly following the loop clause. ex. A=1 REPEAT (PRINT A IF A>100 BREAK ELSE A=A+1) .LOOP ) .IF CMD=='CALL' ( CALL: Call a named macro. The word CALL is optional a macro name is itself a valid CLONE statement. ex. CALL HELP is the same as HELP CALLable macros are those files on ML:[100,100] having extension .CL1 and a file name beginning with a letter. .LOOP ) .IF CMD=='AT' ( @: This command is similar to CALL except that the macro invoked may be in any file. The @ must be immediatly followed by an RSX file specification. ex. @DK1:MYMACRO The default device is SY: and the default UIC is that of the calling terminal. If the extension is not specified the file is first looked up as .CL1 and if this fails .CMD is tried. The file extension determines the mode in which the macro is initialy executed. if the extension is CLONE mode (see command CLONE) whilst if the extension is .CMD the initial execution mode is LITERAL (see command LITERAL). See command PASS and SUSPEND for additional uses of the command @. .LOOP ) .IF CMD=='ENABLE ^ CMD==DISABLE' ( ENABLE, DISABLE: These commands are used to turn on and off certain CLONE functions. Each can take any one of the following keywords as an argument: SUBSTITUTION of variables into string literals LOG of replies TRACE of CLONE command lines TEXT print rather than reply 'replies' LITERAL do not parse for clone commands ex. ENABLE SUBSTITUTION .LOOP ) .IF CMD=='DO' ( DO: This is a standard loop clause with a numeric control variable. The basic form is: DO i=e1,e2,e3 statement The statement is executed for values of the loop variable i in increments of e3 between e1 and e2. If e3 is omitted an increment of +1 is assumed. Unlike the FORTRAN DO loop if e2 is initialy less than e1 and e3 is positive the loop is never executed, similarly if e1 is initialy less than e2 and e3 is negative. If e3 is zero the loop is infinite. The statements BREAK and NEXT may be used within a DO loop to transfer control out of the loop or back to the top respectivly. ex. DO I=1,10 PRINT I,I*I .LOOP ) .IF CMD=='END' ^ CMD==')' ( END OR (: END is not an executable statement. It is the BLOCK terminator and must occure at the same LEXICAL LEVEL as the begin which it matches. END may thus not be the subject of any clause. .LOOP ) .IF CMD=='FOR' ( FOR: The FOR loop provides a general loop in which the loop variable is assigned each of a set of values in sequence. FOR a=e1,e2,e3...en statement The statement is executed once with each value e1 to en in turn assigned to a. The values in the list may be of any type and if expressions are evaluated immediatly prior to their assignment to the loop variable. A typical use of the FOR loop would be execution of a program with a set of file names. ex. FOR N='FRED','JIM','MARY','JOANNE','PETER' RUN PROC ( 100 100 'ADD' N 1 1 '') .LOOP ) .IF CMD=='GET' ^ CMD=='[' ( GET: GET returns a value which has been previously RECORDED by a task running under CLONE. If no value is available the issueing macro suspends until a RECORD is issued. Note that the use of GET assumes that the programmer has provided appropriate calls in the application program. ex. RUN FRED (X Y Z A=GET) PRINT A A compound form is available which REPLYs a value the the program and GETs a result. This form is useful with certain specialy written utility programs. ex. REPLY X A=GET can be replaced by: A=[X] .LOOP ) .IF CMD=='IF' ( IF: The IF clause has three forms: 1) IF q THEN s1 ELSE s2 2) IF q THEN s1 3) IF q C [ELSE s] The first form is fully general. q is any expression which can be converted to yield a logical result (yes/no or true/false). s1 and s2 are any CLONE statements and will frequently be BLOCKS. In the second case the else clause has been omitted. The resolution of a 'dangling else' in nested IF clauses is performed by binding each ELSE to the nearest UN-ELSED IF. In the third case the THEN is omitted. This is permitted when the statement c is a CLONE command name. ex. IF q BREAK is valid, but IF q A=3 is not. As indicated the ELSE is optional in this case too. The IF statement may return a value. ex. A=IF q THEN 3 ELSE 4 Where the 3 and 4 could be any expressions. .LOOP ) .IF CMD=='LITERAL' ^ CMD=='CLONE' ( LITERAL and CLONE: LITERAL mode enables CLONE to process indirect files in much the same way as RSX MCR commands whilst still taking advantage of CLONE features. The statements LITERAL and CLONE enable and disable LITERAL mode respectivly. In LITERAL mode, command lines are not parsed by the CLONE syntax processor unless their first character is one of the special characters described below, lines of text are transformed into literal text replies as though they were entirely enclosed in quotes. Two special characters provide escapes from LITERAL mode: . and @ If a command line begins with . then the line is parsed as a normal CLONE line excluding the '.'. If a line begins with @ the line is parsed as described elsewhere for the command @. To exit from literal mode the command CLONE must occure on a line beginning with '.'. ex. LITERAL THIS LINE IS REPLIED AS TEXT .A # REPLY THE VALUE OF A @XXYY # CALL AN INDIRECT FILE THIS IS ANOTHER TEXT REPLY .CLONE # RETURN TO CLONE MODE Note that comments are only valid in CLONE mode lines. .LOOP ) .IF CMD=='LOG' ^ CMD=='NOLOG' ( LOG and NOLOG: LOG enables listing of all transactions between programs and macros and between macros and macros. In general if LOG is enabled questions and answers will appear on the terminal as though they were being typed however other operations such as CALLs RETURNs and RECORDs are also logged. The Command NOLOG disables LOG mode. .LOOP ) .IF CMD=='LOOP' ( LOOP: LOOP like BREAK is used within a LOOP clause to cause an immediate return to the top of the loop. It may be described more exactly as a jump to the point immediatly after the last statement of the loop. This vew clarifies the behavure in DO loops. .LOOP ) .IF CMD=='MCR' ( MCR: This command provides a simple means for CLONE to issue MCR commands to RSX. The form of the command is: MCR statement Where statement may be a single REPLY or may be a BLOCK providing many REPLYs. Within an MCR block all REPLYs which would otherwise be sent to a program are issued as MCR commands. ex. MCR ('PIP *.TMP;*/DE' 'PIP /FR') .LOOP ) .IF CMD=='PASS' ( PASS n or @ n: The PASS command causes CLONE to pass the next n questions posed by the task under CLONE control directly to the console. This avoids unessescary questions and REPLYs within CLONE macros. n may be a numeric CLONE expression. In the special case where n is omitted the command acts as SUSPEND. .LOOP ) .IF CMD=='PRINT' ( PRINT: PRINT outputs text and CLONE values to the terminal (TI:). Each PRINT statement outputs on a new line but a single statement may output any number of values. ex. PRINT I,J,K Value separators may be ',' ';' or ':' to separate the text with tab, space or nothing respectivly. ex. PRINT 'I=':I,'J=':J A PRINT statement without arguments produces a blank line. .LOOP ) .IF CMD=='REPEAT' ( REPEAT: The REPEAT clause is the simplest form of LOOP. The statement following the command is executed repetativly until one of: STOP, RETURN or BREAK is executed. ex. A=1 REPEAT IF A>100 BREAK ELSE (PRINT A A=A+1)' .LOOP ) .IF CMD=='REPLY' ( REPLY: The REPLY statement is the principal statement of the command language. The statement: REPLY e Causes the value of the expression e to be passed to a program running under CLONE control as though it had been typed at a terminal. The word REPLY is optional and any expression occuring in a context where no value is required is interpreted as a reply. The REPLY statement usualy occurs within a RUN-BLOCK ex. RUN FRED (1 2 3 4) Which causes the program FRED to RUN and REPLIES the values 1,2,3,4 to its first four questions. If the program exits before all the replies have been accepted the remainder is ignored. .LOOP ) .IF CMD=='RESUME' ( RESUME: The RESUME command is used to resume a macro which has suspended. As the macro is not executing RESUME must be issued from a breakin command. If a program is running and posing questions, typing the escape key to any question will resume the suspended macro, otherwise if no question is posed the CL1 MCR command must be used to breakin to the suspended macro. When CLONE prompts (CL1>) a reply of RESUME or control-Z will resume the macro. .LOOP ) .IF CMD=='RETURN' ( RETURN: The RETURN command instructs the CLONE processor to return the macro routine being processed before the last CALL or @file statement. If the current routine was not CALLed RETURN is equivalent to STOP. An implicit RETURN is executed when an end of macro file is reached. .LOOP ) .IF CMD=='RUN' ( RUN: RUN causes a named program to execute and may supply it with data in the form of REPLIES. The basic form of RUN is: RUN PROG s Where PROG is the name of an installed task and s is a possibly null CLONE expression. s will generaly be a BLOCK containing REPLYS and data computations in this case s is refered to as a RUN-BLOCK. ex. RUN FRED (A=2 A*3 A*4) Here a variable is initialized and used in the computation of two REPLYs to program FRED. Clone control does not continue past the end of the RUN-BLOCK until the program exits. Thus any further questions are posed directly to the console. Conversely if the program exits before the end of the RUN-BLOCK computations within the block take place but all REPLYs are null. .LOOP ) .IF CMD=='STACK' ( STACK: The STACK command is an information command which displays the values of all variables defined at each lexical level. The current type of each variable is indicated by enclosing strings in quotation marks. .LOOP ) .IF CMD=='STOP' ( STOP: The STOP command terminates execution of the issuing macro. If a program is being run all its remaining questions are posed directly to the console. .LOOP ) .IF CMD=='SUSPEND' ( SUSPEND or @: The SUSPEND command causes execution of the issuing macro to suspend until a RESUME command is given. Questions posed by the program until the RESUME is issued are passed directly to the console. SUSPEND provides a mechanism for inputting data of indeterminate length and of suspending operations after some error condition while corrections are made. The command may be issued by an executing macro or as a breakin command. Note that if the @ form is used it must be the last command on the line to avoid confusion with the @ n construction. .LOOP ) .IF CMD=='SYS' ( SYS: SYS is an information command which provides information on all CLONE processes and streams active. The command prints for each active terminal the list of active macros and tasks. In addition status and flag values are printed for each process and stream. Consult CLONE system documentation for interpretation of these flags. .LOOP ) .IF CMD=='TEXT' ^ CMD=='NOTEXT' ( TEXT and NOTEXT: The TEXT and NOTEXT commands respectivly enable and disable text mode. In text mode all REPLYs are printed on the terminal rather than being sent to a task. This is useful for outputting large quantities of information as in this macro. TEXT is most useful in conjunction with LITERAL mode. .LOOP ) .IF CMD=='TRACE' ^ CMD=='NOTRACE' ( TRACE and NOTRACE: The TRACE and NOTRACE commands respectivly enable and disable tracing of CLONE command lines as they are executed. When tracing is enabled each line is printed as it is executed. Lines beginning in false conditional context are not printed. .LOOP ) .IF CMD=='UNLESS' ( UNLESS: The UNLESS command systax is identical to that of IF however the IF condition is the compliment of the logical expression. ex. UNLESS c PRINT x is the same as IF !c PRINT x .LOOP ) .IF CMD=='UPDATE' ( UPDATE: The UPDATE command must be used if a CLONE system macro. That is a macro file on ML:[100,100] is modified and is to be called without re-starting CLONE. This may often be the case in a multi-user environment. The UPDATE command associates any new versions of macro files with their names in the system macro table. If CLONE exits before the new macro is called UPDATE is not required as the new version will be found in CLONE initialisation. .LOOP ) .IF CMD=='EXPRESSIONS' ( CLONE expressions: Arithmetic operators: +,-,*,/ String concatenation: $+ relations: ==, !=, <, <=, >, >=, $= Logical operators: !(not), &(and), ^(or) Parenthesese may be used freely as required. Operands may be literals, CLONE variables or VALUED CLONE commands (such as ASK). CLONE variable names are 1-80 characters from 0-9 and a-z and A-Z starting with a letter. Upper- and lower-case names are distinct. The range for numeric values is -32767 to 32767. Division by zero and integer overflow generate non-fatal errors. String equality is determined to the end of the left operand. Thus a null left operand will match anything. .LOOP ) .IF CMD=='CONSOLE' ^ CMD=='COMMANDS' ( CONSOLE COMMANDS: CLONE macros are generaly invoked by typing @NAME to a question posed by a program or another macro. NAME is an RSX file specification (see command AT) indicating the macro to be executed. To issue any CLONE command type the command followed by the ESCAPE key, this is known as immediate mode. If the command is null CLONE prompts CL1> for a command. ESCAPE has special significance when typed to a question posed by a CLONE macro. In this case it generates a BREAKIN of the the macro execution and permits examination and modification of macro variables. BREAKIN mode is terminated by either RESUME or CONTROL-Z. When no question is posed (as in an infinatly looping macro) a BREAKIN may be created with the CL1 MCR command. Summary: @NAME execute macro file named. @ connect to clone (immediate mode). If CLONE is not active connect (immediate mode). If CLONE is active BREAKIN current macro. If CLONE is suspended RESUME command If CLONE is not active, connect and execute. If CLONE is active, BREAKIN and execute. If CLONE is suspended, BREAKIN and RESUME on termination of command. .LOOP ) .PRINT 'COMMAND '$+CMD$+' NOT KNOWN' )