home *** CD-ROM | disk | FTP | other *** search
/ Power Programming / powerprogramming1994.iso / progtool / plot / 3dplot02.arc / 3DPLOT.DOC < prev    next >
Text File  |  1989-06-25  |  20KB  |  421 lines

  1.  
  2.  
  3.  
  4.                                    3DPLOT
  5.  
  6.  
  7.  
  8.              3DPLOT plots z=f(x,y) in three dimensions.
  9.  
  10.              The function f(x,y) is defined in two files.  They  have
  11.         the same file name, but one has the extension INI and one has
  12.         the extension XYZ.  Both files are subroutines programmed  in
  13.         a  PL/I-like  language.   The INI routine is called once when
  14.         3DPLOT  is  started;   variables  set  in  this  routine  are
  15.         available  to  the XYZ routine.  The XYZ routine calculates z
  16.         from x and y.  It is called once for each x and  y.   Neither
  17.         file may exceed 16383 bytes in length.
  18.  
  19.              The PL/I-like routines are punctuated as in PL/I.
  20.  
  21.              The data types Boolean (corresponding to PL/I's BIT(1)),
  22.         integer  (corresponding  to  PL/I's  FIXED  BINARY(31)), real
  23.         (corresponding   to   PL/I's   FLOAT   BINARY(53)),    string
  24.         (corresponding  to  PL/I's  CHAR(32767)  VARYING),  and  file
  25.         pointer are supported.
  26.  
  27.              Comparison, the  function  TRUE  (corresponding  to  the
  28.         constant '1'B in PL/I), and the function FALSE (corresponding
  29.         to the constant '0'B in PL/I) return Boolean values.
  30.  
  31.              Integers are written as in PL/I.
  32.  
  33.              Reals are written as in PL/I except that a decimal point
  34.         MUST  be preceded by a digit.  (Thus 0.1 is acceptable but .1
  35.         isn't.)
  36.  
  37.              Strings are written as in PL/I.
  38.  
  39.              Comments are started with  "/*"  and  ended  with  "*/".
  40.         They may not be nested.
  41.  
  42.              The OPEN function are used to create file pointers.
  43.  
  44.              Variable names must start with a letter and  consist  of
  45.         letters,  digits,  or  underscores.  There are no declaration
  46.         statements; the type of a variable is the same as the type of
  47.         whatever  was last assigned to it.  Calculations on reals and
  48.         integers produce reals.  Reals and integers are  compared  as
  49.         reals.  Otherwise, no implicit conversions are performed.
  50.  
  51.              Arrays  with  any  number  of  subscripts are supported.
  52.         Unlike PL/I, any data type may be used as a  subscript.   For
  53.         instance, "friend('Jimmy')='Mary';" is allowed.  When a value
  54.         is assigned to an array element, subscripts  of  exactly  the
  55.         same  type  must be used to reference it.  Thus, "a(1.0)" and
  56.         "a(1)" are not the same.  (In the first case,  the  subscript
  57.         is  a  real; in the second case the subscript is an integer.)
  58.         Unlike PL/I, elements of an array must be referenced one at a
  59.         time.   And,  the  first  reference  to an array element must
  60.         assign a value to it.
  61.  
  62.  
  63.  
  64.              The  PL/I  structures  "IF...THEN",  "IF...THEN...ELSE",
  65.         "DO;...END;",  and  "DO  WHILE"  are supported. "SELECT", "DO
  66.         UNTIL", iterative DO, etc. are not  supported.   Beware  that
  67.         carriage return /  line feeds are ignored.  As a consequence,
  68.         THEN and ELSE must be followed by at least one space (on  the
  69.         same or next line); a carriage return / line feed won't do.
  70.  
  71.              The following infix operators are supported:
  72.  
  73.  
  74.                   * multiplication   + addition         = equality
  75.                   / division         - subtraction     != inequality
  76.                   & logical and      | logical or       < less than
  77.                                     || concatenation   <= less than or equal
  78.                                                         > greater than
  79.                                                        >= greater than or equal
  80.  
  81.              Multiplication,  division, addition, and subtraction may
  82.         only be performed on integers and reals.  AND and OR may only
  83.         be   performed   on  Booleans.   Concatenation  may  only  be
  84.         performed on strings.  The comparison operators may  only  be
  85.         used to compare two operands of the same type or to compare a
  86.         real and an integer.  In the latter  case,  the  items  being
  87.         compared  are  converted  to  reals  before the comparison is
  88.         made. "Less than", "less than or equal", "greater than",  and
  89.         "greater than or equal" may not be applied to Booleans.
  90.  
  91.              In  the  absence  of  parentheses, the operations in the
  92.         first column above are performed as they occur from  left  to
  93.         right   before  the  operations  in  the  second  column  are
  94.         performed from left to right before  the  operations  in  the
  95.         third  column  are performed from left to right.  Parentheses
  96.         may be used to override the order  in  which  operations  are
  97.         performed.
  98.  
  99.              Notice  that  there  is no exponentiation operator "**".
  100.         Use the fact that a**b = EXP(b*LOG(a)) for a > 0.
  101.  
  102.              Booleans may be negated by the operator  "!".   Integers
  103.         and reals may be negated by the operator "-".
  104.  
  105.              Unlike  PL/I, the user may not define his own functions.
  106.         However, the following functions are built in:
  107.  
  108.                   ABS(arg) returns the absolute value of an
  109.                   argument  "arg".   The  argument  must be
  110.                   either real or integer.  The  result  has
  111.                   the same type as the argument.
  112.  
  113.                   ATAN(arg)  returns  the arctangent of the
  114.                   argument "arg".   The  argument  must  be
  115.                   either  real  or  integer.  The result is
  116.                   real.
  117.  
  118.  
  119.  
  120.                   CHAR(arg) returns  the  character  having
  121.                   extended ASCII value "arg".  The argument
  122.                   must be an integer  between  0  and  255,
  123.                   inclusively.  The result is a string.
  124.  
  125.                   COS(arg)   returns   the  cosine  of  the
  126.                   argument "arg".   The  argument  must  be
  127.                   either real or integer.  It is assumed to
  128.                   be in radians.  The result is real.
  129.  
  130.                   DATE returns the current date  as  a  six
  131.                   character  string  in  the  form  YYMMDD,
  132.                   where YY is the last two  digits  of  the
  133.                   year,  MM is the number of the month, and
  134.                   DD is the number of the  day  within  the
  135.                   month.
  136.  
  137.                   ENDFILE(arg)  returns  TRUE  if  the file
  138.                   pointed to by "arg" is at  end  of  file.
  139.                   Otherwise,  it  returns  FALSE.   If  the
  140.                   argument and parentheses are omitted, the
  141.                   file defaults to SYSIN.
  142.  
  143.                   EXEC(arg)  executes  the  PC  DOS command
  144.                   contained in the string  "arg".   If  the
  145.                   command  is  successfully  executed,  the
  146.                   Boolean  value  for  true  is   returned.
  147.                   Otherwise,   the   value   for  false  is
  148.                   returned.
  149.  
  150.                   EXP(arg) returns e (2.71828...) raised to
  151.                   the  power  "arg".   The argument must be
  152.                   either real or integer.   The  result  is
  153.                   real.
  154.  
  155.                   FALSE   returns  the  Boolean  value  for
  156.                   false.  It takes no arguments.
  157.  
  158.                   FLOAT(arg) converts an argument "arg"  to
  159.                   real.  For a Boolean argument, it returns
  160.                   1.0 for  TRUE  and  0.0  for  FALSE.   It
  161.                   converts   an  integer  argument  to  the
  162.                   corresponding   real.    Given   a   real
  163.                   argument, it returns the argument.  Given
  164.                   a string, it  converts  as  much  of  the
  165.                   string   as  possible  to  a  real.   For
  166.                   example, "FLOAT('3.14x')"  returns  3.14.
  167.                   The  argument  to FLOAT may not be a file
  168.                   pointer.
  169.  
  170.                   GETCHAR(arg) returns (as  a  string)  the
  171.                   next  character  from the file pointed to
  172.                   by "arg".  At end of file (where there is
  173.                   no  next  character), it returns a string
  174.                   of length  zero.   If  the  argument  and
  175.                   parentheses   are   omitted,   the   file
  176.                   defaults to SYSIN.
  177.  
  178.  
  179.  
  180.                   GETINT(arg) returns the next integer from
  181.                   the  file  pointed  to  by "arg".  If the
  182.                   argument and parentheses are omitted, the
  183.                   file defaults to SYSIN.
  184.  
  185.                   GETREAL(arg)  returns  the next real from
  186.                   the file pointed to  by  "arg".   If  the
  187.                   argument and parentheses are omitted, the
  188.                   file defaults to SYSIN.
  189.  
  190.                   GETSTRING(arg) returns the next line from
  191.                   the  file  pointed  to  by "arg".  If the
  192.                   argument and parentheses are omitted, the
  193.                   file  defaults to SYSIN.  A line consists
  194.                   of all characters preceding the next line
  195.                   feed  or end of file, excluding any final
  196.                   carriage  return;   GETSTRING   functions
  197.                   like "LINE INPUT" in Microsoft BASIC.
  198.  
  199.                   INDEX(arg1,arg2)  returns (as an integer)
  200.                   the position of the string "arg2" in  the
  201.                   string      "arg1".      For     example,
  202.                   "INDEX('CABLE','ABLE')"  returns  2.   If
  203.                   the second argument does not occur in the
  204.                   first argument, or  either  argument  has
  205.                   length zero, 0 is returned.
  206.  
  207.                   LENGTH(arg)  returns  (as an integer) the
  208.                   number of characters in the string "arg".
  209.  
  210.                   LINENO takes no arguments and returns the
  211.                   number of the line in the program source.
  212.                   (It  does  not  function  like  the  PL/I
  213.                   LINENO function.)
  214.  
  215.                   LOG(arg) returns the natural logarithm of
  216.                   the argument "arg".  The argument must be
  217.                   real or integer.  In either case, it must
  218.                   be positive.  The result is real.
  219.  
  220.                   MOD(arg1,arg2) returns the  remainder  of
  221.                   "arg1"  divided  by  "arg2".  That is, it
  222.                   returns    arg1-arg2*(arg1/arg2).     The
  223.                   arguments must be integers and the second
  224.                   argument may not be zero.  The result  is
  225.                   integer.
  226.  
  227.                   OPEN(arg1,arg2)  opens  the  file with PC
  228.                   DOS file name "arg1". "arg2" is the  mode
  229.                   in  which  the  file  is opened.  In text
  230.                   mode, carriage return / line  feed  pairs
  231.                   are  converted  into  line feeds on input
  232.                   and  line  feeds   are   converted   into
  233.                   carriage   return / line  feed  pairs  on
  234.                   output.  In binary mode,  no  translation
  235.  
  236.  
  237.  
  238.                   occurs.   Use  'w'  to  open  a  file for
  239.                   output in text mode.  If the file exists,
  240.                   it  will  be deleted before it is opened.
  241.                   Use 'r' to  open  an  existing  file  for
  242.                   input  in  text  mode.  Use 'a' to open a
  243.                   file for appending in text mode.  If  the
  244.                   file  does not exist, it will be created.
  245.                   Concatenate a '+' to the mode to  open  a
  246.                   file   for   both   input   and   output.
  247.                   Concatenate a 'b' to the mode to  open  a
  248.                   file  in  binary  mode  (instead  of text
  249.                   mode).             For            example
  250.                   "file=OPEN('C:\USER\WORK\TEST.DAT','r+b')
  251.                   ;"     would      open      the      file
  252.                   "C:\USER\WORK\TEST.DAT"   for  input  and
  253.                   output  in  binary  mode,  if  the   file
  254.                   exists.   Both arguments must be strings.
  255.                   The mode must  be  in  lower  case.   The
  256.                   result is a pointer to the file.
  257.  
  258.                   ORD(arg1)   returns  the  extended  ASCII
  259.                   value  of  the  first  character  in  the
  260.                   string "arg1".  The argument must contain
  261.                   at least one character.  The result is an
  262.                   integer.   For  example, ORD('A') returns
  263.                   65.
  264.  
  265.                   PI takes no  arguments  and  returns  the
  266.                   value of pi (3.14159...).
  267.  
  268.                   REPEAT(arg1,arg2)  returns   the   string
  269.                   "arg1"  concatenated  with  itself "arg2"
  270.                   times. "arg1" must be a string and "arg2"
  271.                   must   be  a  nonnegative  integer.   The
  272.                   result  is  a   string.    For   example,
  273.                   REPEAT('A',1) returns 'A'.  If the second
  274.                   argument is zero or negative,  the  first
  275.                   argument is returned.
  276.  
  277.                   SIN(arg) returns the sine of the argument
  278.                   "arg".  The argument must be either  real
  279.                   or  integer.   It  is  assumed  to  be in
  280.                   radians.  The result is real.
  281.  
  282.                   SQR(arg)  returns  the  square   of   the
  283.                   argument  "arg".   The  argument  must be
  284.                   either real or integer.  The  result  has
  285.                   the same type as the argument.
  286.  
  287.                   SQRT(arg)  returns the square root of the
  288.                   argument "arg".   The  argument  must  be
  289.                   either  real or integer.  In either case,
  290.                   it must be nonnegative.   The  result  is
  291.                   real.
  292.  
  293.  
  294.  
  295.                   STR(arg)  converts  the argument "arg" to
  296.                   the string that would be printed  by  the
  297.                   procedure  PRINT.  The argument may be of
  298.                   any type; the result is a string.
  299.  
  300.                   SUBSTR(arg1,arg2) returns  the  substring
  301.                   of  the string "arg1" beginning at column
  302.                   "arg2".  The first  argument  must  be  a
  303.                   string.   The  second argument must be an
  304.                   integer between 1 and the length  of  the
  305.                   first argument, inclusively.
  306.  
  307.                   SUBSTR(arg1,arg2,arg3)   returns   "arg3"
  308.                   characters of the string "arg1"  starting
  309.                   with  the  "arg2"-th character of "arg1".
  310.                   The first argument must be a string.  The
  311.                   other  two  arguments  must  be integers.
  312.                   The result is  a  string.   It  must  lie
  313.                   entirely  within  the first argument.  If
  314.                   the last argument is zero,  a  string  of
  315.                   length zero is returned.
  316.  
  317.                   SYSIN  takes  no  arguments and returns a
  318.                   pointer  to  the  standard  input   file.
  319.                   Unless  overridden  on  the  command line
  320.                   when 3DPLOT is executed, the keyboard  is
  321.                   the standard input file.
  322.  
  323.                   SYSPRINT takes no arguments and returns a
  324.                   pointer  to  the  standard  output  file.
  325.                   Unless  overridden  on  the  command line
  326.                   when   3DPLOT   is  executed,  the  video
  327.                   display is the standard output file.
  328.  
  329.                   TIME  takes  no arguments and returns the
  330.                   time of day as a nine character string in
  331.                   the  format  HHMMSSmmm,  where  HH is the
  332.                   hour in a 24 hour day, MM is  the  minute
  333.                   within  the hour, SS is the second within
  334.                   the  minute,  and  mmm  is  always  three
  335.                   zeros.
  336.  
  337.                   TRANSLATE(arg1,arg2,arg3)    returns    a
  338.                   character string of the  same  length  as
  339.                   the  string "arg1".  All of the arguments
  340.                   are strings.  Initially  the  result  has
  341.                   length  zero.   Proceeding left to right,
  342.                   for each character in the first argument,
  343.                   if  the  character  is  found in the i-th
  344.                   position in the third argument, then  the
  345.                   i-th  character of the second argument is
  346.                   appended to the end of the  result.   (If
  347.                   necessary,  the second argument is padded
  348.                   with spaces.) If  the  character  is  not
  349.                   found   in  the  third  argument,  it  is
  350.                   appended without change  to  the  result.
  351.                   If  the  third argument is not specified,
  352.  
  353.  
  354.                   it is assumed to be  the  extended  ASCII
  355.                   collating           sequence           --
  356.                   CHAR(0)||CHAR(1)||...||CHAR(255).
  357.  
  358.                   TRUNC(arg) converts an argument "arg"  to
  359.                   an  integer.   For a Boolean argument, it
  360.                   returns 1  for  TRUE  and  0  for  FALSE.
  361.                   Given an integer argument, it returns the
  362.                   argument.   Given  a  real  argument,  it
  363.                   returns   the   integer   part   of  that
  364.                   argument.   For   example   "TRUNC(-3.9)"
  365.                   returns  -3.  Given a string, it converts
  366.                   as much of the string as  possible  to  a
  367.                   real.    For   example,  "FLOAT('3.14x')"
  368.                   returns 3.  The argument to TRUNC may not
  369.                   be a file pointer.
  370.  
  371.                   TRUE  returns the Boolean value for true.
  372.                   It takes no arguments.
  373.  
  374.                   UPPER(arg1)  returns  the  string  "arg1"
  375.                   converted to upper case.
  376.  
  377.                   VERIFY(arg1,arg2) returns (as an integer)
  378.                   the position in the string "arg1" of  the
  379.                   leftmost  character  not  in  the  string
  380.                   "arg2".  If  all  of  the  characters  in
  381.                   "arg1"   appear   in   "arg2",   zero  is
  382.                   returned.  If  "arg1"  has  length  zero,
  383.                   zero is returned.  If "arg1" has positive
  384.                   length and "arg2" has length zero, one is
  385.                   returned.
  386.  
  387.              Unlike PL/I, the user may not define his own procedures.
  388.         In fact, the verb "CALL" is not used.  However, the following
  389.         procedures are built in:
  390.  
  391.                   CLOSE(arg1)  closes  the  file associated
  392.                   with file pointer "arg1".
  393.  
  394.                   CLRSCR clears the video display.
  395.  
  396.                   PRINT(arg1,arg2,...argn)   prints   arg2,
  397.                   arg3, ..., argn on the file pointed to by
  398.                   arg1.
  399.  
  400.                   PUTCRLF  prints  a  line  feed   on   the
  401.                   standard output file.
  402.  
  403.                   PUTCRLF(arg1)  prints  a line feed on the
  404.                   file associated with file pointer "arg1".
  405.                   If  the  file  is  open  in  text mode, a
  406.                   carriage return / line  feed  combination
  407.                   will be output.
  408.  
  409.                   TROFF turns trace off.  It functions like
  410.                   TROFF in Microsoft BASIC.
  411.  
  412.  
  413.  
  414.                   TRON turns trace on.  If  functions  like
  415.                   TRON  in  Microsoft  BASIC; when trace is
  416.                   on, the line number of a source statement
  417.                   is  printed  just before the statement is
  418.                   executed.  The  line  number  is  printed
  419.                   within  square  brackets  on the standard
  420.                   output file.
  421.