Programmer Power Tools

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

/ Programmer Power Tools / Programmer Power Tools.iso / pli / runpli1a.arc / RUN.DOC < prev next >

Wrap

Text File | 1988-04-22 | 24.5 KB | 577 lines

RUN RUN is a PC DOS program that interprets a PL/I-like programs. The PL/I-like programs are punctuated as in PL/I. The data types Boolean (corresponding to PL/I's BIT(1)), integer (corresponding to PL/I's FIXED BINARY(31)), real (corresponding to PL/I's FLOAT BINARY(53)), string (corresponding to PL/I's CHAR(32767) VARYING), and file pointer are supported. Comparison, the function TRUE (corresponding to the constant '1'B in PL/I), and the function FALSE (corresponding to the constant '0'B in PL/I) return Boolean values. Integers are written as in PL/I. Reals are written as in PL/I except that a decimal point MUST be preceded by a digit. (Thus 0.1 is acceptable but .1 isn't.) Strings are written as in PL/I. The OPEN function are used to create file pointers. Variable names must start with a letter and consist of letters, digits, or underscores. There are no declaration statements; the type of a variable is the same as the type of whatever was last assigned to it. Calculations on reals and integers produce reals. Reals and integers are compared as reals. Otherwise, no implicit conversions are performed. Arrays with any number of subscripts are supported. Unlike PL/I, any data type may be used as a subscript. For instance, "friend('Jimmy')='Mary';" is allowed. When a value is assigned to an array element, subscripts of exactly the same type must be used to reference it. Thus, "a(1.0)" and "a(1)" are not the same. (In the first case, the subscript is a real; in the second case the subscript is an integer.) Unlike PL/I, elements of an array must be referenced one at a time. And, the first reference to an array element must assign a value to it. In the spirit of C, when RUN is started, the string variables ARGV(1), ARGV(2), ... contain the arguments from the command line, starting with the name of the file being interpreted by RUN. The variable ARGC gives the total number of arguments. For example, if the PC DOS command "RUN SUPERDIR C:\USER\C\PDI" is issued, ARGC is 2, ARGV(1)='SUPERDIR', and ARGV(2)='C:\USER\C\PDI'. The PL/I structures "IF...THEN", "IF...THEN...ELSE", "DO;...END;", and "DO WHILE" are supported. "SELECT", "DO UNTIL", iterative DO, etc. are not supported. Beware that carriage return / line feeds are ignored. As a consequence, THEN and ELSE must be followed by at least one space (on the same or next line); a carriage return / line feed won't do. The following infix operators are supported: * multiplication + addition = equality / division - subtraction != inequality & logical and | logical or < less than || concatenation <= less than or equal > greater than >= greater than or equal Multiplication, division, addition, and subtraction may only be performed on integers and reals. AND and OR may only be performed on Booleans. Concatenation may only be performed on strings. The comparison operators may only be used to compare two operands of the same type or to compare a real and an integer. In the latter case, the items being compared are converted to reals before the comparison is made. "Less than", "less than or equal", "greater than", and "greater than or equal" may not be applied to Booleans. In the absence of parentheses, the operations in the first column above are performed as they occur from left to right before the operations in the second column are performed from left to right before the operations in the third column are performed from left to right. Parentheses may be used to override the order in which operations are performed. Notice that there is no exponentiation operator "**". Use the fact that a**b = EXP(b*LOG(a)) for a > 0. Booleans may be negated by the operator "!". Integers and reals may be negated by the operator "-". Unlike PL/I, the user may not define his own functions. However, the following functions are built in: ABS(arg) returns the absolute value of an argument "arg". The argument must be either real or integer. The result has the same type as the argument. ATAN(arg) returns the arctangent of the argument "arg". The argument must be either real or integer. The result is real. CHAR(arg) returns the character having extended ASCII value "arg". The argument must be an integer between 0 and 255, inclusively. The result is a string. COS(arg) returns the cosine of the argument "arg". The argument must be either real or integer. It is assumed to be in radians. The result is real. DATE returns the current date as a six character string in the form YYMMDD, where YY is the last two digits of the year, MM is the number of the month, and DD is the number of the day within the month. ENDFILE(arg) returns TRUE if the file pointed to by "arg" is at end of file. Otherwise, it returns FALSE. If the argument and parentheses are omitted, the file defaults to SYSIN. EXEC(arg) executes the PC DOS command contained in the string "arg". If the command is successfully executed, the Boolean value for true is returned. Otherwise, the value for false is returned. EXP(arg) returns e (2.71828...) raised to the power "arg". The argument must be either real or integer. The result is real. FALSE returns the Boolean value for false. It takes no arguments. FLOAT(arg) converts an argument "arg" to real. For a Boolean argument, it returns 1.0 for TRUE and 0.0 for FALSE. It converts an integer argument to the corresponding real. Given a real argument, it returns the argument. Given a string, it converts as much of the string as possible to a real. For example, "FLOAT('3.14x')" returns 3.14. The argument to FLOAT may not be a file pointer. GETCHAR(arg) returns (as a string) the next character from the file pointed to by "arg". At end of file (where there is no next character), it returns a string of length zero. If the argument and parentheses are omitted, the file defaults to SYSIN. GETINT(arg) returns the next integer from the file pointed to by "arg". If the argument and parentheses are omitted, the file defaults to SYSIN. GETREAL(arg) returns the next real from the file pointed to by "arg". If the argument and parentheses are omitted, the file defaults to SYSIN. GETSTRING(arg) returns the next line from the file pointed to by "arg". If the argument and parentheses are omitted, the file defaults to SYSIN. A line consists of all characters preceding the next line feed or end of file, excluding any final carriage return; GETSTRING functions like "LINE INPUT" in Microsoft BASIC. INDEX(arg1,arg2) returns (as an integer) the position of the string "arg2" in the string "arg1". For example, "INDEX('CABLE','ABLE')" returns 2. If the second argument does not occur in the first argument, or either argument has length zero, 0 is returned. LENGTH(arg) returns (as an integer) the number of characters in the string "arg". LINENO takes no arguments and returns the number of the line in the program source. (It does not function like the PL/I LINENO function.) LOG(arg) returns the natural logarithm of the argument "arg". The argument must be real or integer. In either case, it must be positive. The result is real. MOD(arg1,arg2) returns the remainder of "arg1" divided by "arg2". That is, it returns arg1-arg2*(arg1/arg2). The arguments must be integers and the second argument may not be zero. The result is integer. OPEN(arg1,arg2) opens the file with PC DOS file name "arg1". "arg2" is the mode in which the file is opened. In text mode, carriage return / line feed pairs are converted into line feeds on input and line feeds are converted into carriage return / line feed pairs on output. In binary mode, no translation occurs. Use 'w' to open a file for output in text mode. If the file exists, it will be deleted before it is opened. Use 'r' to open an existing file for input in text mode. Use 'a' to open a file for appending in text mode. If the file does not exist, it will be created. Concatenate a '+' to the mode to open a file for both input and output. Concatenate a 'b' to the mode to open a file in binary mode (instead of text mode). For example "file=OPEN('C:\USER\WORK\TEST.DAT','r+b') ;" would open the file "C:\USER\WORK\TEST.DAT" for input and output in binary mode, if the file exists. Both arguments must be strings. The mode must be in lower case. The result is a pointer to the file. ORD(arg1) returns the extended ASCII value of the first character in the string "arg1". The argument must contain at least one character. The result is an integer. For example, ORD('A') returns 65. PI takes no arguments and returns the value of pi (3.14159...). PLIRETV takes no arguments and returns the current value of the PC DOS return code. The result is an integer. This value is zero when RUN starts and can be set to another value by the procedure PLIRETC. If a fatal error is detected by RUN, it is set to 2000. If RUN is executed as part of a PC DOS batch file, the PC DOS ERRORLEVEL is set to this return code after RUN executes. REPEAT(arg1,arg2) returns the string "arg1" concatenated with itself "arg2" times. "arg1" must be a string and "arg2" must be a nonnegative integer. The result is a string. For example, REPEAT('A',1) returns 'A'. If the second argument is zero or negative, the first argument is returned. SIN(arg) returns the sine of the argument "arg". The argument must be either real or integer. It is assumed to be in radians. The result is real. SQR(arg) returns the square of the argument "arg". The argument must be either real or integer. The result has the same type as the argument. SQRT(arg) returns the square root of the argument "arg". The argument must be either real or integer. In either case, it must be nonnegative. The result is real. STR(arg) converts the argument "arg" to the string that would be printed by the procedure PRINT. The argument may be of any type; the result is a string. SUBSTR(arg1,arg2) returns the substring of the string "arg1" beginning at column "arg2". The first argument must be a string. The second argument must be an integer between 1 and the length of the first argument, inclusively. SUBSTR(arg1,arg2,arg3) returns "arg3" characters of the string "arg1" starting with the "arg2"-th character of "arg1". The first argument must be a string. The other two arguments must be integers. The result is a string. It must lie entirely within the first argument. If the last argument is zero, a string of length zero is returned. SYSIN takes no arguments and returns a pointer to the standard input file. Unless overridden on the command line when RUN is executed, the keyboard is the standard input file. SYSPRINT takes no arguments and returns a pointer to the standard output file. Unless overridden on the command line when RUN is executed, the video display is the standard output file. TIME takes no arguments and returns the time of day as a nine character string in the format HHMMSSmmm, where HH is the hour in a 24 hour day, MM is the minute within the hour, SS is the second within the minute, and mmm is always three zeros. TRANSLATE(arg1,arg2,arg3) returns a character string of the same length as the string "arg1". All of the arguments are strings. Initially the result has length zero. Proceeding left to right, for each character in the first argument, if the character is found in the i-th position in the third argument, then the i-th character of the second argument is appended to the end of the result. (If necessary, the second argument is padded with spaces.) If the character is not found in the third argument, it is appended without change to the result. If the third argument is not specified, it is assumed to be the extended ASCII collating sequence -- CHAR(0)||CHAR(1)||...||CHAR(255). TRUNC(arg) converts an argument "arg" to an integer. For a Boolean argument, it returns 1 for TRUE and 0 for FALSE. Given an integer argument, it returns the argument. Given a real argument, it returns the integer part of that argument. For example "TRUNC(-3.9)" returns -3. Given a string, it converts as much of the string as possible to a real. For example, "FLOAT('3.14x')" returns 3. The argument to TRUNC may not be a file pointer. TRUE returns the Boolean value for true. It takes no arguments. UPPER(arg1) returns the string "arg1" converted to upper case. VERIFY(arg1,arg2) returns (as an integer) the position in the string "arg1" of the leftmost character not in the string "arg2". If all of the characters in "arg1" appear in "arg2", zero is returned. If "arg1" has length zero, zero is returned. If "arg1" has positive length and "arg2" has length zero, one is returned. Unlike PL/I, the user may not define his own procedures. In fact, the verb "CALL" is not used. However, the following procedures are built in: CLOSE(arg1) closes the file associated with file pointer "arg1". CLRSCR clears the video display. PLIRETC(arg) sets the PC DOS return code. The argument must be an integer. If the value of the argument is between 0 and 999, the return code is set to that value. Otherwise, the return code is set to 999. The function PLIRETV can be used to determine the current value of the return code. After RUN is executed as part of a PC DOS batch file, the PC DOS ERRORLEVEL has the last value of this return code. PRINT(arg1,arg2,...argn) prints arg2, arg3, ..., argn on the file pointed to by arg1. PUTCRLF prints a line feed on the standard output file. PUTCRLF(arg1) prints a line feed on the file associated with file pointer "arg1". If the file is open in text mode, a carriage return / line feed combination will be output. TROFF turns trace off. It functions like TROFF in Microsoft BASIC. TRON turns trace on. If functions like TRON in Microsoft BASIC; when trace is on, the line number of a source statement is printed just before the statement is executed. The line number is printed within square brackets on the standard output file. Sample Program The following program sorts the lines in a file (without regard to case) and outputs the result to a file: CLRSCR; PRINT(SYSPRINT,REPEAT(' ',36),'Sort'); PUTCRLF; PUTCRLF; PUTCRLF; PRINT(SYSPRINT,'Input file descriptor? '); input_file_descriptor=GETSTRING; infile=OPEN(input_file_descriptor,'r'); infile_eof=FALSE; num_lines=0; DO WHILE(! infile_eof); tem_string=GETSTRING(infile); IF ENDFILE(infile) THEN infile_eof=TRUE; ELSE DO; num_lines=num_lines+1; line(num_lines)=tem_string; END; END; PRINT(SYSPRINT,'Output file descriptor? '); output_file_descriptor=GETSTRING; outfile=OPEN(output_file_descriptor,'w'); IF num_lines > 0 THEN DO; left=num_lines/2; left=left+1; right=num_lines; tem_string=line(1); finished=FALSE; DO WHILE(right > 1); IF left > 1 THEN DO; left=left-1; tem_string=line(left); END; ELSE DO; tem_string=line(right); line(right)=line(1); right=right-1; END; IF right > 1 THEN DO; key_index_2=left; finished=FALSE; DO WHILE(! finished); key_index_1=key_index_2; key_index_2=2*key_index_2; IF key_index_2 > right THEN finished=TRUE; ELSE DO; IF key_index_2 != right THEN DO; IF UPPER(line(key_index_2)) < UPPER(line(key_index_2+1)) THEN key_index_2=key_index_2+1; END; IF UPPER(tem_string) >= UPPER(line(key_index_2)) THEN finished=TRUE; ELSE DO; line(key_index_1)=line(key_index_2); END; END; END; line(key_index_1)=tem_string; END; END; line(1)=tem_string; line_num=1; DO WHILE(line_num <= num_lines); PRINT(outfile,line(line_num)); PUTCRLF(outfile); line_num=line_num+1; END; END; CLOSE(outfile);