home *** CD-ROM | disk | FTP | other *** search
/ Power Programming / powerprogramming1994.iso / progtool / pli / runpli1a.arc / RUN.DOC < prev    next >
Text File  |  1988-04-22  |  25KB  |  577 lines

  1.  
  2.  
  3.  
  4.  
  5.                                      RUN
  6.  
  7.  
  8.  
  9.              RUN  is  a  PC  DOS  program that interprets a PL/I-like
  10.         programs.
  11.  
  12.              The PL/I-like programs are punctuated as in PL/I.
  13.  
  14.              The data types Boolean (corresponding to PL/I's BIT(1)),
  15.         integer  (corresponding  to  PL/I's  FIXED  BINARY(31)), real
  16.         (corresponding   to   PL/I's   FLOAT   BINARY(53)),    string
  17.         (corresponding  to  PL/I's  CHAR(32767)  VARYING),  and  file
  18.         pointer are supported.
  19.  
  20.              Comparison, the  function  TRUE  (corresponding  to  the
  21.         constant '1'B in PL/I), and the function FALSE (corresponding
  22.         to the constant '0'B in PL/I) return Boolean values.
  23.  
  24.              Integers are written as in PL/I.
  25.  
  26.              Reals are written as in PL/I except that a decimal point
  27.         MUST  be preceded by a digit.  (Thus 0.1 is acceptable but .1
  28.         isn't.)
  29.  
  30.              Strings are written as in PL/I.
  31.  
  32.              The OPEN function are used to create file pointers.
  33.  
  34.              Variable names must start with a letter and  consist  of
  35.         letters,  digits,  or  underscores.  There are no declaration
  36.         statements; the type of a variable is the same as the type of
  37.         whatever  was last assigned to it.  Calculations on reals and
  38.         integers produce reals.  Reals and integers are  compared  as
  39.         reals.  Otherwise, no implicit conversions are performed.
  40.  
  41.              Arrays  with  any  number  of  subscripts are supported.
  42.         Unlike PL/I, any data type may be used as a  subscript.   For
  43.         instance, "friend('Jimmy')='Mary';" is allowed.  When a value
  44.         is assigned to an array element, subscripts  of  exactly  the
  45.         same  type  must be used to reference it.  Thus, "a(1.0)" and
  46.         "a(1)" are not the same.  (In the first case,  the  subscript
  47.         is  a  real; in the second case the subscript is an integer.)
  48.         Unlike PL/I, elements of an array must be referenced one at a
  49.         time.   And,  the  first  reference  to an array element must
  50.         assign a value to it.
  51.  
  52.              In the spirit of C, when  RUN  is  started,  the  string
  53.         variables  ARGV(1),  ARGV(2),  ... contain the arguments from
  54.         the command line, starting with the name of  the  file  being
  55.         interpreted by RUN.  The variable ARGC gives the total number
  56.         of arguments.  For  example,  if  the  PC  DOS  command  "RUN
  57.         SUPERDIR    C:\USER\C\PDI"    is    issued,    ARGC   is   2,
  58.         ARGV(1)='SUPERDIR', and ARGV(2)='C:\USER\C\PDI'.
  59.  
  60.  
  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.                   CHAR(arg) returns  the  character  having
  119.  
  120.  
  121.  
  122.  
  123.                   extended ASCII value "arg".  The argument
  124.                   must be an integer  between  0  and  255,
  125.                   inclusively.  The result is a string.
  126.  
  127.                   COS(arg)   returns   the  cosine  of  the
  128.                   argument "arg".   The  argument  must  be
  129.                   either real or integer.  It is assumed to
  130.                   be in radians.  The result is real.
  131.  
  132.                   DATE returns the current date  as  a  six
  133.                   character  string  in  the  form  YYMMDD,
  134.                   where YY is the last two  digits  of  the
  135.                   year,  MM is the number of the month, and
  136.                   DD is the number of the  day  within  the
  137.                   month.
  138.  
  139.                   ENDFILE(arg)  returns  TRUE  if  the file
  140.                   pointed to by "arg" is at  end  of  file.
  141.                   Otherwise,  it  returns  FALSE.   If  the
  142.                   argument and parentheses are omitted, the
  143.                   file defaults to SYSIN.
  144.  
  145.                   EXEC(arg)  executes  the  PC  DOS command
  146.                   contained in the string  "arg".   If  the
  147.                   command  is  successfully  executed,  the
  148.                   Boolean  value  for  true  is   returned.
  149.                   Otherwise,   the   value   for  false  is
  150.                   returned.
  151.  
  152.                   EXP(arg) returns e (2.71828...) raised to
  153.                   the  power  "arg".   The argument must be
  154.                   either real or integer.   The  result  is
  155.                   real.
  156.  
  157.                   FALSE   returns  the  Boolean  value  for
  158.                   false.  It takes no arguments.
  159.  
  160.                   FLOAT(arg) converts an argument "arg"  to
  161.                   real.  For a Boolean argument, it returns
  162.                   1.0 for  TRUE  and  0.0  for  FALSE.   It
  163.                   converts   an  integer  argument  to  the
  164.                   corresponding   real.    Given   a   real
  165.                   argument, it returns the argument.  Given
  166.                   a string, it  converts  as  much  of  the
  167.                   string   as  possible  to  a  real.   For
  168.                   example, "FLOAT('3.14x')"  returns  3.14.
  169.                   The  argument  to FLOAT may not be a file
  170.                   pointer.
  171.  
  172.                   GETCHAR(arg) returns (as  a  string)  the
  173.                   next  character  from the file pointed to
  174.                   by "arg".  At end of file (where there is
  175.                   no  next  character), it returns a string
  176.                   of length  zero.   If  the  argument  and
  177.                   parentheses   are   omitted,   the   file
  178.                   defaults to SYSIN.
  179.  
  180.  
  181.  
  182.  
  183.  
  184.                   GETINT(arg) returns the next integer from
  185.                   the  file  pointed  to  by "arg".  If the
  186.                   argument and parentheses are omitted, the
  187.                   file defaults to SYSIN.
  188.  
  189.                   GETREAL(arg)  returns  the next real from
  190.                   the file pointed to  by  "arg".   If  the
  191.                   argument and parentheses are omitted, the
  192.                   file defaults to SYSIN.
  193.  
  194.                   GETSTRING(arg) returns the next line from
  195.                   the  file  pointed  to  by "arg".  If the
  196.                   argument and parentheses are omitted, the
  197.                   file  defaults to SYSIN.  A line consists
  198.                   of all characters preceding the next line
  199.                   feed  or end of file, excluding any final
  200.                   carriage  return;   GETSTRING   functions
  201.                   like "LINE INPUT" in Microsoft BASIC.
  202.  
  203.                   INDEX(arg1,arg2)  returns (as an integer)
  204.                   the position of the string "arg2" in  the
  205.                   string      "arg1".      For     example,
  206.                   "INDEX('CABLE','ABLE')"  returns  2.   If
  207.                   the second argument does not occur in the
  208.                   first argument, or  either  argument  has
  209.                   length zero, 0 is returned.
  210.  
  211.                   LENGTH(arg)  returns  (as an integer) the
  212.                   number of characters in the string "arg".
  213.  
  214.                   LINENO takes no arguments and returns the
  215.                   number of the line in the program source.
  216.                   (It  does  not  function  like  the  PL/I
  217.                   LINENO function.)
  218.  
  219.                   LOG(arg) returns the natural logarithm of
  220.                   the argument "arg".  The argument must be
  221.                   real or integer.  In either case, it must
  222.                   be positive.  The result is real.
  223.  
  224.                   MOD(arg1,arg2) returns the  remainder  of
  225.                   "arg1"  divided  by  "arg2".  That is, it
  226.                   returns    arg1-arg2*(arg1/arg2).     The
  227.                   arguments must be integers and the second
  228.                   argument may not be zero.  The result  is
  229.                   integer.
  230.  
  231.                   OPEN(arg1,arg2)  opens  the  file with PC
  232.                   DOS file name "arg1". "arg2" is the  mode
  233.                   in  which  the  file  is opened.  In text
  234.                   mode, carriage return / line  feed  pairs
  235.                   are  converted  into  line feeds on input
  236.                   and  line  feeds   are   converted   into
  237.                   carriage   return / line  feed  pairs  on
  238.                   output.  In binary mode,  no  translation
  239.  
  240.  
  241.  
  242.  
  243.                   occurs.   Use  'w'  to  open  a  file for
  244.                   output in text mode.  If the file exists,
  245.                   it  will  be deleted before it is opened.
  246.                   Use 'r' to  open  an  existing  file  for
  247.                   input  in  text  mode.  Use 'a' to open a
  248.                   file for appending in text mode.  If  the
  249.                   file  does not exist, it will be created.
  250.                   Concatenate a '+' to the mode to  open  a
  251.                   file   for   both   input   and   output.
  252.                   Concatenate a 'b' to the mode to  open  a
  253.                   file  in  binary  mode  (instead  of text
  254.                   mode).             For            example
  255.                   "file=OPEN('C:\USER\WORK\TEST.DAT','r+b')
  256.                   ;"     would      open      the      file
  257.                   "C:\USER\WORK\TEST.DAT"   for  input  and
  258.                   output  in  binary  mode,  if  the   file
  259.                   exists.   Both arguments must be strings.
  260.                   The mode must  be  in  lower  case.   The
  261.                   result is a pointer to the file.
  262.  
  263.                   ORD(arg1)   returns  the  extended  ASCII
  264.                   value  of  the  first  character  in  the
  265.                   string "arg1".  The argument must contain
  266.                   at least one character.  The result is an
  267.                   integer.   For  example, ORD('A') returns
  268.                   65.
  269.  
  270.                   PI takes no  arguments  and  returns  the
  271.                   value of pi (3.14159...).
  272.  
  273.                   PLIRETV  takes  no  arguments and returns
  274.                   the current value of the  PC  DOS  return
  275.                   code.   The  result  is an integer.  This
  276.                   value is zero when RUN starts and can  be
  277.                   set  to  another  value  by the procedure
  278.                   PLIRETC.  If a fatal error is detected by
  279.                   RUN,  it  is  set  to  2000.   If  RUN is
  280.                   executed as part of a PC DOS batch  file,
  281.                   the  PC  DOS  ERRORLEVEL  is  set to this
  282.                   return code after RUN executes.
  283.  
  284.                   REPEAT(arg1,arg2)  returns   the   string
  285.                   "arg1"  concatenated  with  itself "arg2"
  286.                   times. "arg1" must be a string and "arg2"
  287.                   must   be  a  nonnegative  integer.   The
  288.                   result  is  a   string.    For   example,
  289.                   REPEAT('A',1) returns 'A'.  If the second
  290.                   argument is zero or negative,  the  first
  291.                   argument is returned.
  292.  
  293.                   SIN(arg) returns the sine of the argument
  294.                   "arg".  The argument must be either  real
  295.                   or  integer.   It  is  assumed  to  be in
  296.                   radians.  The result is real.
  297.  
  298.                   SQR(arg)  returns  the  square   of   the
  299.  
  300.  
  301.  
  302.  
  303.                   argument  "arg".   The  argument  must be
  304.                   either real or integer.  The  result  has
  305.                   the same type as the argument.
  306.  
  307.                   SQRT(arg)  returns the square root of the
  308.                   argument "arg".   The  argument  must  be
  309.                   either  real or integer.  In either case,
  310.                   it must be nonnegative.   The  result  is
  311.                   real.
  312.  
  313.                   STR(arg)  converts  the argument "arg" to
  314.                   the string that would be printed  by  the
  315.                   procedure  PRINT.  The argument may be of
  316.                   any type; the result is a string.
  317.  
  318.                   SUBSTR(arg1,arg2) returns  the  substring
  319.                   of  the string "arg1" beginning at column
  320.                   "arg2".  The first  argument  must  be  a
  321.                   string.   The  second argument must be an
  322.                   integer between 1 and the length  of  the
  323.                   first argument, inclusively.
  324.  
  325.                   SUBSTR(arg1,arg2,arg3)   returns   "arg3"
  326.                   characters of the string "arg1"  starting
  327.                   with  the  "arg2"-th character of "arg1".
  328.                   The first argument must be a string.  The
  329.                   other  two  arguments  must  be integers.
  330.                   The result is  a  string.   It  must  lie
  331.                   entirely  within  the first argument.  If
  332.                   the last argument is zero,  a  string  of
  333.                   length zero is returned.
  334.  
  335.                   SYSIN  takes  no  arguments and returns a
  336.                   pointer  to  the  standard  input   file.
  337.                   Unless  overridden  on  the  command line
  338.                   when RUN is executed, the keyboard is the
  339.                   standard input file.
  340.  
  341.                   SYSPRINT takes no arguments and returns a
  342.                   pointer  to  the  standard  output  file.
  343.                   Unless  overridden  on  the  command line
  344.                   when RUN is executed, the  video  display
  345.                   is the standard output file.
  346.  
  347.                   TIME  takes  no arguments and returns the
  348.                   time of day as a nine character string in
  349.                   the  format  HHMMSSmmm,  where  HH is the
  350.                   hour in a 24 hour day, MM is  the  minute
  351.                   within  the hour, SS is the second within
  352.                   the  minute,  and  mmm  is  always  three
  353.                   zeros.
  354.  
  355.                   TRANSLATE(arg1,arg2,arg3)    returns    a
  356.                   character string of the  same  length  as
  357.                   the  string "arg1".  All of the arguments
  358.                   are strings.  Initially  the  result  has
  359.  
  360.  
  361.  
  362.  
  363.                   length  zero.   Proceeding left to right,
  364.                   for each character in the first argument,
  365.                   if  the  character  is  found in the i-th
  366.                   position in the third argument, then  the
  367.                   i-th  character of the second argument is
  368.                   appended to the end of the  result.   (If
  369.                   necessary,  the second argument is padded
  370.                   with spaces.) If  the  character  is  not
  371.                   found   in  the  third  argument,  it  is
  372.                   appended without change  to  the  result.
  373.                   If  the  third argument is not specified,
  374.                   it is assumed to be  the  extended  ASCII
  375.                   collating           sequence           --
  376.                   CHAR(0)||CHAR(1)||...||CHAR(255).
  377.  
  378.                   TRUNC(arg) converts an argument "arg"  to
  379.                   an  integer.   For a Boolean argument, it
  380.                   returns 1  for  TRUE  and  0  for  FALSE.
  381.                   Given an integer argument, it returns the
  382.                   argument.   Given  a  real  argument,  it
  383.                   returns   the   integer   part   of  that
  384.                   argument.   For   example   "TRUNC(-3.9)"
  385.                   returns  -3.  Given a string, it converts
  386.                   as much of the string as  possible  to  a
  387.                   real.    For   example,  "FLOAT('3.14x')"
  388.                   returns 3.  The argument to TRUNC may not
  389.                   be a file pointer.
  390.  
  391.                   TRUE  returns the Boolean value for true.
  392.                   It takes no arguments.
  393.  
  394.                   UPPER(arg1)  returns  the  string  "arg1"
  395.                   converted to upper case.
  396.  
  397.                   VERIFY(arg1,arg2) returns (as an integer)
  398.                   the position in the string "arg1" of  the
  399.                   leftmost  character  not  in  the  string
  400.                   "arg2".  If  all  of  the  characters  in
  401.                   "arg1"   appear   in   "arg2",   zero  is
  402.                   returned.  If  "arg1"  has  length  zero,
  403.                   zero is returned.  If "arg1" has positive
  404.                   length and "arg2" has length zero, one is
  405.                   returned.
  406.  
  407.              Unlike PL/I, the user may not define his own procedures.
  408.         In fact, the verb "CALL" is not used.  However, the following
  409.         procedures are built in:
  410.  
  411.                   CLOSE(arg1)  closes  the  file associated
  412.                   with file pointer "arg1".
  413.  
  414.                   CLRSCR clears the video display.
  415.  
  416.  
  417.                   PLIRETC(arg) sets the PC DOS return code.
  418.                   The  argument must be an integer.  If the
  419.  
  420.  
  421.  
  422.  
  423.                   value of the argument is  between  0  and
  424.                   999,  the  return  code  is  set  to that
  425.                   value.  Otherwise, the return code is set
  426.                   to 999.  The function PLIRETV can be used
  427.                   to determine the  current  value  of  the
  428.                   return  code.   After  RUN is executed as
  429.                   part of a PC DOS batch file, the  PC  DOS
  430.                   ERRORLEVEL  has  the  last  value of this
  431.                   return code.
  432.  
  433.                   PRINT(arg1,arg2,...argn)   prints   arg2,
  434.                   arg3, ..., argn on the file pointed to by
  435.                   arg1.
  436.  
  437.                   PUTCRLF  prints  a  line  feed   on   the
  438.                   standard output file.
  439.  
  440.                   PUTCRLF(arg1)  prints  a line feed on the
  441.                   file associated with file pointer "arg1".
  442.                   If  the  file  is  open  in  text mode, a
  443.                   carriage return / line  feed  combination
  444.                   will be output.
  445.  
  446.                   TROFF turns trace off.  It functions like
  447.                   TROFF in Microsoft BASIC.
  448.  
  449.                   TRON turns trace on.  If  functions  like
  450.                   TRON  in  Microsoft  BASIC; when trace is
  451.                   on, the line number of a source statement
  452.                   is  printed  just before the statement is
  453.                   executed.  The  line  number  is  printed
  454.                   within  square  brackets  on the standard
  455.                   output file.
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.                                Sample Program
  487.  
  488.              The following program sorts the lines in a file (without
  489.         regard to case) and outputs the result to a file:
  490.  
  491.                   CLRSCR;
  492.                   PRINT(SYSPRINT,REPEAT(' ',36),'Sort');
  493.                   PUTCRLF;
  494.                   PUTCRLF;
  495.                   PUTCRLF;
  496.                   PRINT(SYSPRINT,'Input file descriptor? ');
  497.                   input_file_descriptor=GETSTRING;
  498.                   infile=OPEN(input_file_descriptor,'r');
  499.                   infile_eof=FALSE;
  500.                   num_lines=0;
  501.                   DO WHILE(! infile_eof);
  502.                     tem_string=GETSTRING(infile);
  503.                     IF ENDFILE(infile) THEN
  504.                       infile_eof=TRUE;
  505.                     ELSE
  506.                       DO;
  507.                         num_lines=num_lines+1;
  508.                         line(num_lines)=tem_string;
  509.                       END;
  510.                   END;
  511.                   PRINT(SYSPRINT,'Output file descriptor? ');
  512.                   output_file_descriptor=GETSTRING;
  513.                   outfile=OPEN(output_file_descriptor,'w');
  514.                   IF num_lines > 0 THEN
  515.                     DO;
  516.                       left=num_lines/2;
  517.                       left=left+1;
  518.                       right=num_lines;
  519.                       tem_string=line(1);
  520.                       finished=FALSE;
  521.                       DO WHILE(right > 1);
  522.                         IF left > 1 THEN
  523.                           DO;
  524.                             left=left-1;
  525.                             tem_string=line(left);
  526.                           END;
  527.                         ELSE
  528.                           DO;
  529.                             tem_string=line(right);
  530.                             line(right)=line(1);
  531.                             right=right-1;
  532.                           END;
  533.                         IF right > 1 THEN
  534.                           DO;
  535.                             key_index_2=left;
  536.                             finished=FALSE;
  537.                             DO WHILE(! finished);
  538.                               key_index_1=key_index_2;
  539.  
  540.  
  541.  
  542.  
  543.                               key_index_2=2*key_index_2;
  544.                               IF key_index_2 > right THEN
  545.                                 finished=TRUE;
  546.                               ELSE
  547.                                 DO;
  548.                                   IF key_index_2 != right THEN
  549.                                     DO;
  550.                                       IF UPPER(line(key_index_2))
  551.                                        < UPPER(line(key_index_2+1)) THEN
  552.                                         key_index_2=key_index_2+1;
  553.                                     END;
  554.                                   IF UPPER(tem_string)
  555.                                    >= UPPER(line(key_index_2)) THEN
  556.                                     finished=TRUE;
  557.                                   ELSE
  558.                                     DO;
  559.                                       line(key_index_1)=line(key_index_2);
  560.                                     END;
  561.                                 END;
  562.                             END;
  563.                             line(key_index_1)=tem_string;
  564.                           END;
  565.                       END;
  566.                       line(1)=tem_string;
  567.                       line_num=1;
  568.                       DO WHILE(line_num <= num_lines);
  569.                         PRINT(outfile,line(line_num));
  570.                         PUTCRLF(outfile);
  571.                         line_num=line_num+1;
  572.                       END;
  573.                     END;
  574.                   CLOSE(outfile);
  575.  
  576. 
  577.