HELPnEThe COD (COmponent Definition) program is intended to fill two roles: BFirst, it can be used interactively as a reverse-Polish calculator>using all the functions described in the 'dictionary' section. GSecond, it can be used to test COD programs as described in the 'files'section. @In all cases, COD will accept several commands on a single line. dictionaryfiles=forthDfuture{WGEt`List bNewparfQuitgRUngStepkversionn,CThe following functions are built-in to the current version of COD:+8-*/6^DEPth0DRopDUP+OVerPICKROLL$ ROTH SWap ?DupG ABS NEGE 1/ PI LNV EXP LOG/ALogSQrtCOSSINTANUACosASin.ATanA2tn HCosHSinHTanzINTNInt^MOD/MOD{TSig8DTorRTod!DMsd|DDmsq0<0=0>NOT.1+01-2+2-NMINMAX3STO+STO6!RCL"?Z#VAR$:%;3(ABOrt( program_words)%Add the top two numbers in the stack. Example:  5.0 2.0COD> + 7.0*Subtract the top two numbers in the stack. Example:  5.0 2.0COD> - 3.0*Multiply the top two numbers in the stack. Example:  5.0 2.0COD> * 10.0DDivide the previously entered number by the number on the top of thestack. Example:  5.0 2.0COD> / 2.5ARaise the previously entered number to the power given by the topnumber in the stack. Example:  5.0 2.0COD> ^ 25.0CLeave the number of values contained in the stack (not counting theresult). Example:  5.0 4.0COD> DEP 5.0 4.0 2.0DDrop the stack pointer so that the number at the top of the stack islost. Example:  5.0 4.0 COD> DROP 5.0DDuplicate the number on the top of the stack (equivalent to 1 PICK). Example:  5.0 2.0COD> DUP 5.0 2.0 2.0@Duplicate the second number on the stack (equivalent to 2 PICK). Example:  5.0 4.0 COD> OVER 5.0 4.0 5.0DDuplicate the nth number on the stack (not counting n itself), whereCn is the top number on the stack. Note: 1 PICK does the same thing/as DUP, and 2 PICK does the same thing as OVER. Example: 100. 200. 300. 400. COD> 3 PICK 100. 200. 300. 400. 200.?Rotate the nth number (not counting n itself) to the top of theBstack, where n the top number in the stack. Note: 2 ROLL does theAsame thing as SWAP; 3 ROLL does the same thing as ROT; and n mustbe greater than 1.0. Example: 100. 200. 300. 400. COD> 4 ROLL 200. 300. 400. 100.GRotate the third number to the top of the stack (equivalent to 3 ROLL). Example: 100. 200. 300. 400.COD> ROT 100. 300. 400. 200.=Swap the top two numbers on the stack (equivalent to 2 ROLL). Example:  5.0 2.0 COD> SWap 2.0 5.0DDuplicate the number at the top of the stack only if it is non-zero. Example: 5.0 0.0 COD> ?DUP 5.0 0.0 COD> 1.0 ?DUP 5.0 0.0 1.0 1.07Take the absolute value of the top number in the stack. Example: 5.0 -2.0COD> ABS 5.0 2.0#Negate the top number in the stack. Example:  5.0 2.0COD> NEG 5.0 -2.03Compute the inverse of the top number in the stack. Example:  5.0 2.0COD> 1/ 5.0 0.50$Push the value of PI into the stack. Example:  5.0COD> PI 5.0 3.1415934Take the natural log of the top number in the stack. Example:  5.0 2.0COD> LN 5.0 0.69314727Compute the exponential of the top number in the stack. Example:  5.0 1.0COD> EXP 5.0 2.718282:Take the base-10 logarithm of the top number in the stack. Example:  5.0 2.0COD> LN 5.0 0.3010300?Compute 10. raised to the power of the top number in the stack. Example:  5.0 2.0 COD> ALog 5.0 100.07Compute the square-root of the top number in the stack. Example:  5.0 2.0 COD> SQrt 5.0 1.4142142Compute the cosine of the top number in the stack. Example:  5.0 0.5COD> COS 5.0 0.87758260Compute the sine of the top number in the stack. Example:  5.0 0.5COD> SIN 5.0 0.47942553Compute the tangent of the top number in the stack. Example:  5.0 0.5COD> TAN 5.0 0.54630256Compute the arc-cosine of the top number in the stack. Example:  5.0 0.5 COD> ACos 5.0 1.0471984Compute the arc-sine of the top number in the stack. Example:  5.0 0.5 COD> ASin 5.0 0.52359887Compute the arc-tangent of the top number in the stack. Example:  5.0 0.5 COD> ATan 5.0 0.4636476;Compute the arc-tangent if the top two numbers in the stackrepresent an x,y pair. Example:  1.0 2.0 COD> A2tn 1.570796=Compute the hyperbolic-cosine of the top number in the stack. Example:  5.0 0.5 COD> HCos 5.0 1.127626;Compute the hyperbolic-sine of the top number in the stack. Example:  5.0 0.5 COD> HSin 5.0 0.5210953>Compute the hyperbolic-tangent of the top number in the stack. Example:  5.0 0.5 COD> HTan 5.0 0.4621172;Compute the integer portion of the top number in the stack. Example:  5.0 0.9COD> INT 5.0 0.07Compute nearest integer to the top number in the stack. Example:  5.0 0.9 COD> NInt 5.0 1.0DCompute the Fortran MOD function (of the previous number, modulo thetop number in the stack. Example:  2.0 3.0COD> MOD 2.0COD> ABO 3.0 3.0 3.0 3.0COD> MOD 0.0?Replace the top two numbers in the stack with the remainder and@quotient of the previous number divided by the top number in thestack. Example: 23.1 10.0 COD> /MOD 3.1 2.0FTransfer the sign of the top number in the stack to the absolute valueof the previous number. Example: 2.0 -5.0 COD> TSig -2.0#Convert decimal degrees to radians. Example: 5.0 90.0 COD> DTor 5.0 1.570796#Convert radians to decimal degrees. Example:  5.0 1.0 COD> RTod 5.0 57.29578:Convert a number of the form DDDMMSS.S to decimal degrees. Example: 123000.0 COD> DMsd 12.5;Convert a number in decimal degrees to the form DDDMMSS.S . Example: 12.5 COD> DMsd 123000.0HReplace the top two numbers in the stack with 1.0 if the previous number+is less than the top number, 0.0 otherwise. Example: 1.0 2.0COD> < 1.0@Replace the top two numbers in the stack with 1.0 if the numbersare equal, 0.0 otherwise. Example: 1.0 2.0COD> = 0.0AReplace the top two numbers in the stack with 1.0 if the previous5number is greater than the top number, 0.0 otherwise. Example: 1.0 2.0COD> > 0.0EReplace the top number in the stack with 1.0 if it is less than zero,0.0 otherwise. Example: -1.0COD> 0< 1.0?Replace the top number in the stack with 1.0 if it equals zero,0.0 otherwise. Example: -1.0COD> 0= 0.0BReplace the top number in the stack with 1.0 if it is greater thanzero, 0.0 otherwise. Example: -1.0COD> 0> 0.0?Replace the top number in the stack with 1.0 if it is zero, 0.0 otherwise. Example: 1.0COD> NOT 0.0EPrint the number at the top of the stack, and decrement stack pointer?by one. The sequence 'DUP .' can be inserted anywhere into CODDprograms to print the number at the top of the stack. This may help)you figure out what the program is doing. Example: 1.0 2.0 3.0 4.0 5.0COD> . 5.0 1.0 2.0 3.0 4.0.Add one to the number at the top of the stack. Example: 3.0 5.0COD> 1+ 3.0 6.05Subtract one from the number at the top of the stack. Example: 3.0 5.0COD> 1- 3.0 4.0.Add two to the number at the top of the stack. Example: 3.0 5.0COD> 2+ 3.0 7.05Subtract two from the number at the top of the stack. Example: 3.0 5.0COD> 2- 3.0 3.0@Replace the top two numbers in the stack with the minimum of the two numbers. Example: 1.0 3.0 5.0COD> MIN 1.0 3.0DReplace the top two numbers in the stack with the maximum of the twonumbers. Example: 1.0 3.0 5.0COD> MAX 1.0 5.0CStore the previous number at the address given by the number at the?top of the stack. Although it is easy to determine the address VAR TMP 1.0COD> 5 TMP STO 1.0 COD> TMP RCL 1.0 5.0AAdd the previous number to the number at the address given by theAnumber at the top of the stack. Although it is easy to determineAthe address associated with a given variable, and hence use thatBaddress directly, it is advisable to always use a variable name to1load an address into the stack before using +STO. Example: COD> VAR TMP 5 TMP STO TMP RCL 5.0 COD> TMP +STO COD> TMP RCL 10.0CReplace the address at the top of the stack with the number at that>address. See the STO topic for an example of how RCL is used.@Display the number stored at the address given at the top of theEstack. Although it is easy to determine the address associated with VAR TMP 5 TMP STO 1.0 2.0 COD> TMP ? 5.0 1.0 2.0@Define the following token to be a new variable name. When thatAvariable is used in the future, it will cause the address of that>variable to be loaded into the stack (for use with a followingSTO or RCL command). Example:COD> VAR 2PI 2 PI * 2PI STO COD> 2PI RCL 6.283185CBegin a new colon definition. In COD, colon definitions define newBdictionary words (i.e., new functions). The token following the :Eis taken to be the name of the function. All words typed after the :@are compiled (stored) into memory. A semicolon ; terminates theDcolon definition and returns the state from compile to execute mode.BThe name must not match any existing COD keyword. The interactive?COD program does not print the stack when the internal state is,compiling (i.e., during a colon definition). Example:COD> : X2 DUP * ; COD> 5 5.0COD> X2 25.0DTerminate the current colon definition and return state from compile1to execute mode. See the : topic for an example.CReset the stack pointer. This deletes all numbers in the stack andBcan be very useful in the interactive mode to clean out the stack.BIf this command occurs while a COD program is running, the program/exits and a NO data function value is returned.)9The following words can only be used inside COD programs:X|*IF*ELSEY,THEN-FOR-LOOPO0+LOOP1I3J=4LEAVE05BEGIN5UNTIL:6WHILE8REPEAT;EXITg<)(Push the current X value into the stack.)DIf the condition is true, execute statements up to the correspondingDELSE/THEN statement. If the condition is false, pass control to theAfirst statement following the ELSE if it exists, otherwise to theAfirst statement following the THEN. IF structures can be nested. Examples: X 1 < IF ! do these statements if X<1 THEN  X 1 > IF ! do these statements if X>1 ELSE ! do these statements if X<=1 THEN)?If the condition was false when the IF statement executed, thenCtransfer control to the first statement following the ELSE. If theBcondition was true then the program executes code down to the ELSEBstatement and then skips to the first statement following the THEN?statement. This statement must be preceeded by an IF statement.)DTerminate an IF structure. See the IF topic for and example of use.)>Set up a FOR..LOOP or a FOR..+LOOP structure using the top two : TMP 4 1 FOR I . LOOP ; COD> TMP 1.0 2.0 3.0 4.0 CWarning to people who know Forth: The COD FOR statement is similarDto the Forth DO statement; however, there is an important difference?concerning the two numbers that precede the FOR. In COD, theseBrepresent the upper and lower index values respectfully; in Forth,;the first number is one greater than the upper index value.)?Terminate a COD FOR loop. When this statement executes, one isDadded to the current index value. If the current index is less thanAor equal to the maximum index, then control is transferred to theFfirst statement following the corresponding FOR statement. Otherwise,Bcontrol passes to the statement following the LOOP statement. See$the FOR topic for an example of use.)CTerminate a COD FOR loop. When this statement executes, the number@at the top of the stack is added to the current index. The loopstatement allows for loops in which the index value can eitherincrease or decrease. Example:!COD> : TMP 0 2 FOR I . -1 +LOOP ; COD> TMP 2.0 1.0 0.0 %COD> : DOUBLE 100 1 FOR I . I +LOOP ; COD> DOUBLE 1.0 2.0 4.0 8.0 16.0 32.0 64.0 COD>)DPush the index value of the innermost FOR loop onto the stack. ThisCstatement can only be used inside FOR loops. See the FOR topic foran example of use.)EPush the index value of the nest outer FOR loop onto the stack. This,statement can only be used inside FOR loops. Example:COD> : TMP 2 1 FORCOD> 5 4 FOR"COD> J . LOOP LOOP ; COD> TMP 1.0 1.0 2.0 2.0)EImmediately exit the current FOR loop. The next statement to executesquares it until it exceeds 1.E10 (note the last number is not printed). COD> VAR Y COD> : TEST 2 Y STO COD> BEGIN,COD> Y RCL . ! Print the number9COD> Y RCL DUP * Y STO ! Square it and store new value COD> Y RCL 1.E10 > ! Test COD> UNTIL ; COD> TEST 2.0 4.0 16.O 256.0 4.2949673E+9)EThe WHILE statement pops one number off the stack. If that number isEtrue (<>0.0), the statement following the WHILE will be executed. If>the number is false then control passes to the first statement?following the REPEAT statement. This statement can only be usedinside a BEGIN..REPEAT loop. Example:=The following program starts with the number 2, and continues2to square that number WHILE it is less than 1.E10. COD> VAR Y COD> : TEST 2 Y STO COD> BEGIN.COD> Y RCL . ! Print the number?COD> Y RCL 1.E10 < WHILE ! Recall number and test for <1.E108COD> Y RCL DUP * Y STO ! Square and store new value COD> REPEAT ; COD> TEST 2.0 4.0 16.O 256.0 4.2949673E+9 1.8446744E+19)ETerminate a BEGIN..WHILE..REPEAT loop. When this statement executes,Ccontrol is always passed to the first statement following the BEGIN6statement. See the WHILE topic for an example of use.)EImmediately terminate the current colon function. Since the stack isEun-affected, check to verify that the stack is left in the same stateEno matter how the colon function is terminated (otherwise obscure andBnasty bugs result). The Surgeon General wishes to remind you thatAusing EXIT will destroy the structured nature of your program and&therefore is hazardous to your health.BCOD can be used to read COD program files from disk. These files,Fcalled COD files, simply contain a sequence of COD built-in functions.CThis sequence of functions is called a COD program. As an example,6assume the file TEST.COD contains the following lines: # ! COD program to calculate a line. ! P1 + P2*X : LINE P1 X P2 * + ; BAll lines that begin with '!' are considered comment lines and areCignored by COD (currently comment lines are listed on your terminalGwhen the file is read in). The third line contains the program itself.EP1 and P2 are parameter values and when used with the PLT/FIT routineGcan be adjusted to minimize chi**2. When writing COD programs that useEparameters, you must use consecutive numbers starting with one, i.e.,'do not leave any holes in the sequence.E The following example demonstrates how the above file can be used.CCOD> GET TEST ! Read the test file, note comment lines are echoed.# ! COD program to calculate a line. ! P1 + P2*X NTERMS= 2'COD> NEW 1 1. ! Set parameter 1 to 1.0 'COD> NEW 2 1. ! Set parameter 2 to 1.0 2COD> 5 ! Place the number 5.0 in the stack 5.07COD> RUN ! Run the program with an X value of 5.0! 6.0 ! The final result AThe COD file must contain a colon definition. Code not containedAin a colon definition are run as the file is read in. Assume the*TMP.COD file contains the following lines:  VAR 2PI 2 PI * 2PI STO : FUNC X 2PI RCL * P1 / COS ; >While this file is being read, the variable 2PI is created and@loaded with the value of 2*PI. The function FUNC can now accessand use this variable. AIf the file contains several : definitions, then it is always the5last definition that the fitting routine in PLT uses.UHBPeople who have used the Forth (Forth is a registered trademark ofBForth, Inc.) computer language will recognize certain similaritiesCwith COD. This is partly by accident since both COD and Forth were>created to solve the problem of making a very fast interpretedBlanguage. Given the similarity, it would be pointless for similar=functions to be implemented differently in the two languages.CTherefore, it is the intention of the current author to add new CODEfunctions using Forth as the model. Thus, with time, COD will evolve?into a dialect of Forth. THERE IS NO INTENTION TO MAKE COD 100BPERCENT COMPATIBLE WITH FORTH. Forth is designed to be a computerElanguage in its own right, whereas, COD is designed to handle advanceAmathematical functions. Since COD programmers will spend most of@their time working in other languages, it will be important that,COD programs are clear and straight forward. differencesHimplementationK omissionsQDFForth uses an integer stack, whereas COD will always use a real stack. Forth ! +! and @EThe ! character denotes a comment in the PLT parser. For consistencyAthis has not been changed. If @ is the first character on a line=then it denotes a request to read an indirect file. To avoidDpotential conflicts, these three functions have been called STO +STO?and RCL (which have the side effect of making COD programs morereadable to outsiders). Forth DOR R< R@DIn Forth users can use the return stack as a temporary place to holdFnumbers. New users are advised to be very careful as the return stackEis used by the system for system booking. Experts use the the returnBstack to write very obscure programs. Due to the fact that in CODEthe main stack is REAL*4 and the return stack is INTEGER*2, using theGreturn stack as a temporary storage location would not work. CurrentlyCCOD does not allow the user to directly manipulate the return stackto encourage cleaner code. - FORTH CONTEXT CURRENT DEFINITIONS VOCABULARY?These words provide Forth a way to give the same word differentAmeanings in different 'modes'. This can result in very confusingDprograms, not to mention very obscure bugs and therefore will not beimplemented in COD.=The current plans are to include a more Forth words into COD. ALLOTDThese words will allow the creation of more general data structures. AND OR XORDIn Forth these words preform bitwise logical operations on INTEGER*2Cnumber. Bitwise logical operations would be rather useless on REALDnumbers, hence COD will use these functions solely as logical tests.AFor example, if the top two numbers on the stack are A and B thenAA B AND will return 1.0 if (A.NE.0 .AND. B.NE.0) otherwise 0.0 is returned.  FORGET CThis word causes all definitions to be erased back to and includingCthe word . This will provide a way for interactive users of*COD to 'erase' their most recent attempts.  ."DThis will be added to print out strings. When this is done then CODDfiles will no longer echo when they are read in. Instead it will beAup to the programmer to put in ." statements, to print out as the%file is read, that document the file.  New COD words: .< >.AIt is impossible to implement Forth style IO in Standard Fortran.DThe current plans are to implement a buffer command. When bufferingAis on then the . word will output to the buffer. When the bufferAis filled, or a line termination condition is set then the bufferAwill be displayed on the users terminal. This will allow ways on=doing formatted IO. The current plans are to use .< to start>buffering and >. to end. Hence, .< . . . >. would print three@numbers on the same line. Once this command is implemented then#several Forth IO words will follow. [ ] LITERAL?These words provide a way of doing a quick calculation inside a:colon definition, but only storing (and using) the result. DThe interactive COD program will be improved. You should be allowedCto single step any colon definition. You should be allowed to save@the current program. You should be allowed to insert and deleteClines from the current program. You should be allowed to set breakApoints. At this stage it is unclear whether the user should makeBchanges in 'text' space or 'compiled code' space or both. Working>in text space would preserve the structure and comments of theAoriginal COD file that was read. Working in code space will give,the user greater control. Comments welcome.!Reads in a COD program. Example,COD> GET POWERMODCwill read in the file POWERMOD.COD from your current directory. The?GET command completely resets all COD internal parameters. AllBexisting colon definitions and variables are forgotten. Note, CODBwords not inside colon definitions will be executed as the file is being read.tbDList can be used to list out the current COD program or the list thecurrent parameter values.Codeb Dictionarycc EquationscPar=f b7This option lists the compiled form of the COD program. 4COD> List C ! will list the entire COD programGCOD> List C 10,20 ! will list lines 10 to 20 of the current COD program b4List all the currently available built-in functions. b5WARNING: This function can fail. Do not use blindly. @This option can be used to view the COD program as a sequence of@equations. In this format, it is sometimes easier to spot bugs. >If the equation is longer than 40 characters then to prevent aCcharacter array overflow, this function define a variable Tx (whereBx is a number). This variable is printed out as Tx=={definition}.@For the rest of the equation the variable Tx is used. Note thisBuse of temporary variables is used only by the listing program and2does not affect the way the function is evaluated. ,Example, consider the following COD program:: TST P1 X P2 * + ; COD> LIST E P1+X*P2 bBThe List Par command is used to list out all the current parametervalues.DAllows you to enter new parameter values when testing a COD program. Example:3COD> GET TEST ! reads in the program in TEST.COD 0COD> NEW 1 2.0 ! sets parameter 1 equal to 2.0 0COD> NEW 2 3.0 ! sets parameter 2 equal to 3.0 GCOD> RUN ! runs program TEST with the current parameter values.Exit from the COD program.@Runs the COD program that was read in with the GEt command. TheBtop number in the stack is stored in X. The stack is then cleared@and the program is run. If the COD file contains any parametersAthen you should set these using the Newpar command. You can alsoDrun a COD program just by entering the name of the colon definition.CHowever, this is not quite the same, and the Run command clears the@stack, whereas if you use the name, the stack is unaffected whenCthe program starts. Also, when using just the name, the X constant?is not loaded. Run should be used to test COD files before useAin PLT/FIT as Running the program will produce the same effect asEcalling it from FIT. If your file contains several colon definitionsBthen Run (and the FIT program) will always run the last definition?in the file. Note, interactively adding more colon definitions=does not affect the program that is run with the Run command.BSingle step the current COD program. The first single step in theCprogram will read an X value of the top of the stack and then resetEthe stack. These actions are the same as when you RUn a COD program.?You are not allowed to Step past a math error or the end of theprogram. Step InitEThis will reset the program counter to the current entry point. ThisChas the effect of restarting the program and is the same thing that%the Run command does before starting. Step [Init] #HWill generate # single Step operations, hence Step 10 will take 10 steps2and Step I 20 will run the first 20 program steps.  . 2005-Apr-22 - Add gamma function called gamm.4 2005-Apr-22 - 0 ^ X now returns 0 if X is non-zero.u are not allowed to Step past a math error or the end of theprogram. Step InitEThis will reset the program counter to the current entry point. ThisChas the effect of restarting the program and is the same thing that%the Run command does before starting. Step [Init] #HWill generate # single Step operations, hence Step 10 will take 10 steps2and Step I 20 will run the first 20 program steps.