JRT Pascal User's Guide version 3.0 NOT FOR SALE -26- 5. Builtin functions JRT Pascal provides numerous builtin functions and several external functions. JRT extensions are indicated with an asterisk. External functions are marked with an 'x'. function return value -------- ------------- ABS absolute value, integer/real * ADDR address of variable x ARCTAN arc tangent CHR convert integer to character * CONCAT concatenate n strings * COPY extract portion of string x COS cosine x EXP exponential * FREE amount of free space * HEX$ convert variable to hex format * LENGTH length of string x LN natural logarithm ODD test for odd value ORD convert character to integer * PORTIN hardware port input * POS search string for pattern PRED preceding value * REAL$ convert real number to string ROUND convert real number to integer x* SEARCH fast table search x SIN sine SQR square, integer/real x SQRT square root SUCC succeeding value TRUNC convert real number to integer * UPCASE convert string to upper case Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -27- 5.1 ABS Format 1 ABS( integer_expression ); Format 2 ABS( real_expression ); The ABS standard function returns the absolute value of an integer or a real expression. Examples: A := ABS( X ); WRITELN( 'ABSOLUTE VALUE IS',ABS( COS( Y ))); B := ABS( X + Y / Z ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -28- 5.2 ADDR Format ADDR( variable ); The ADDR function returns the real address of any variable, array element, field of a record, or dynamic variable. Note that the address of a dynamic variable may change when a storage compression occurs. If the address of a dynamic variable is needed, the ADDR function should be used to obtain the current address immediately before use. Examples: ADDRESS_OF_X := ADDR( X ); AD := ADDR( MATRIX[ X, Y+5 ]); DYN_VAR := ADDR( BASE^ ); DYN_VAR_2 := ADDR( BASE^.NEXT ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -29- 5.3 ARCTAN Format ARCTAN( real_expression ); This standard function returns the arc tangent of a real expression in radians. This is implemented as an external function. The declaration for an external function must be included in programs which reference it. FUNCTION ARCTAN ( X : REAL ): REAL; EXTERN; Examples: WRITELN( ARCTAN( A + 354159 )); NODE.VALUE := OLD_NODE.VALUE + ARCTAN( V ); NOTE: Pi can be conveniently determined by using this function as follows: VAR PI : REAL; FUNCTION ARCTAN ( X : REAL ): REAL; EXTERN; BEGIN PI := 4.0*ARCTAN(1.0); WRITELN('Pi is equivalent to ',PI) END. Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -30- 5.4 CHR Format CHR( integer_expression ); The CHR standard function converts an integer expression into a character. It is often used in sending control characters to output devices. Examples: WRITE( CHR( 12 )); WHILE PORTIN( MODEM ) = CHR(0FFH) DO I:=I+1; TAB := CHR( 9 ); CARRIAGE_RETURN := CHR( 0DH ); LINE_FEED := CHR( OAH ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -31- 5.5 CONCAT Format CONCAT( stringexpr1, stringexpr2,..., stringexprn ); The CONCAT string function concatenates two or more dynamic strings, literal strings, or structured variables. It returns a value of dynamic string of the length required. The plus sign can also be used to concatenate string expressions. Examples: OUTPUT_LINE := CONCAT( NAME, TAB, TAB, PHONE); WRITELN( CONCAT( 'VALUE', OPER, VALUE ); WRITELN( 'VALUE' + OPER + VALUE ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -32- 5.6 COPY Format COPY( string_expression, position, length ); The COPY function returns a string value extracted from the string_expression, beginning at position, for length characters. The position and length parameters are integer expressions. The first character of strings is at position 1. An error will occur if an attempt is made to copy from an area greater than the length of the string. Examples: CH := COPY( 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', CH_NUM, 1 ); WRITELN( COPY( STR, POS( STR,'*' ), 5 ); WRITELN( COPY( 'THIS IS A STRING', 6, 4); (* output of above line is 'IS A' *) Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -33- 5.7 COS Format COS( real_expression ); The COS standard function returns the cosine of a real expression in radians. This is implemented as an external function. The declaration for an external function must be included in programs which reference it. FUNCTION COS ( X : REAL ): REAL; EXTERN; Examples: WRITELN( COS( ANGLE )); NODE.COSINE := COS( N ); WRITELN( COS( VELOCITY / CHARGE )); NOTE: For those who wish to deal in degrees, the following program format should be used: (a similiar program for SIN) VAR PI,DR,COS_45_DEGREES,COS_45_RADIANS : REAL; FUNCTION ARCTAN ( X : REAL ): REAL; EXTERN; FUNCTION COS (X : REAL ): REAL; EXTERN; BEGIN PI := 4.0 * ARCTAN(1.0); DR := PI/180.0; (* CONVERT TO DEGREES *) COS_45_DEGREES := COS ( 45.0 * DR ); COS_45_RADIANS := COS ( 45.0 ); WRITELN( COS_45_DEGREES,' ' COS_45_RADIANS ) END. The output from the above program will be 0.7071067811867 0.5253219888207 Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -34- 5.8 EXP Format EXP( real_expression ); The EXP function computes e to the x power, where x is a real_expression. This is implemented as an external function. The declaration for an external function must be included in programs which reference it. FUNCTION EXP ( X : REAL ): REAL; EXTERN; Examples: X := EXP( Y ); PROJECTED_SALES := 1000 * EXP(YEAR / 100); VOLTAGE := EXP( SIN( PHASE ) ); SHIP_VELOCITY := EXP( WARP_FACTOR ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -35- 5.9 FREE Format FREE The FREE integer function returns the amount of storage currently available. Because the virtual storage manager may delete inactive external procedures, much more storage may be potentially available. The FREE function returns a 16-bit integer value. If more than 32K of storage is available, the value of the integer would print out as negative, due to the limit on integer size. The following function converts unsigned integers to real number format to provide positive representation for numbers up to 65535. FUNCTION REALFREE : REAL; VAR TEMP : INDSGER; BEGIN TEMP := FREE; IF TEMP >= 0 THEN REALFREE := TEMP ELSE REALFREE := 65536.0 + TEMP; END; Examples: WRITELN('FREE SPACE =',FREE); IF REALFREE <= 2000.0 THEN WRITELN('STORAGE CRITICAL'); IF FREE >= 1500 THEN NEW( BUFFER ); IF FREE >= 4096 THEN BUFSIZE := 2048 ELSE BUFSIZE := 1024; RESET( INFILE, 'TEST.DAT', BINARY, BUFSIZE ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -36- 5.10 HEX$ Format HEX$( any_variable ); The HEX$ function converts any variable to hex format for display. The result is of type string and its length is twice the length in bytes of the input variable. Note that the 8080/Z80 microcomputers represent 16 bit integers in byte-reverse format, with low order byte followed by high order byte. That is, +ABCDH would appear in storage as CDABH. The HEX$ function converts all variables as they appear in storage. Often it is useful to display hex integers in the more usual order ABCD. The HEXINT function below makes this conversion: FUNCTION HEXINT ( X : INTEGER ): STRING[4]; VAR A : STRING[4]; BEGIN A := HEX$(X); HEXINT:=' '; HEXINT[1]:=A[3]; HEXINT[2]:=A[4]; HEXINT[3]:=A[1]; HEXINT[4]:=A[2]; END; Examples WRITELN( HEX$( 3.14159 )); WRITELN( HEXINT( ADDR( PTR^ ))); WRITELN( HEXINT( ADDR( FCB ))); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -37- 5.11 LENGTH Format LENGTH( dynamic_string_variable ); The LENGTH function returns an integer value which is the current length of the string variable. IMPORTANT - LENGTH may only be used with dynamic strings variables, not with expressions or any other data type. Examples: WRITELN( LENGTH( STR1 ) ); IF LENGTH(STR1) < 75 THEN STR1:=CONCAT( STR1, '----' ); FOR I:=1 TO LENGTH( NAME ) DO IF NOT (NAME[I] IN ALPHAMERIC) THEN NAME[I]:=' '; Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -38- 5.12 LN Format LN( real_expression ); The LN function computes the natural logarithm of a real expression. This is implemented as an external function. The declaration for an external function must be included in programs which reference it. FUNCTION LN ( X : REAL ): REAL; EXTERN; Examples: X := LN( Y ); WRITELN( LN( X + SQR( Y ) ) ); IF LN( ATOM_WEIGHT ) < 1000.0 THEN WRITELN(F1; ATOM); A := SQRT( LN(Z)); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -39- 5.13 ODD Format ODD( integer_expression ); ODD is a Boolean function which returns the value true if the integer_expression is odd otherwise it returns false. Examples: IF ODD(X) THEN TEST_FOR_PRIME(X); IF ODD(I) THEN I:=I+1; WHILE ODD( PORTIN(15H)) DO X:=X+1.0; WRITELN( ODD(Y) ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -40- 5.14 ORD Format ORD( character_expression ); The ORD function converts a character to an integer value. The character_expression may be a single character or a string. If it is a string, then the first byte will be converted to integer format. The conversion is based on the ASCII character set. This is like the ASC(n) function in most Basics. Examples: REPEAT READ(INFILE; CH) WRITE( CH ); UNTIL ORD(CH) + 1AH; (* EOF *) (* ASCII DISPLAY *) FOR CH := ' ' TO 'z' DO WRITELN( CH, ' = ', ORD(CH)); X := ORD( COPY( S1, I, 1 )); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -41- 5.15 PORTIN Format PORTIN( integer_expression ); The PORTIN function inputs a byte directly from the hardware port specified by the integer_expression. The return value is a character. Examples: IF PORTIN(255) = CHR(80H) THEN WRITELN('HIGH BIT IS ON'); CH := PORTIN(TTY); WHILE PORTIN(MODEM) = CHR(0FFH) DO TIMER := TIMER + 1.0; Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -42- 5.16 POS Format 1 POS( pattern, source ); Format 2 POS( pattern, source, start_position ); Search the source string for the first occurrence of the pattern string. Return the position of the first byte of the pattern if it was found, otherwise return zero. The first byte is position 1. In format 2 of the POS function, the start position of the search in the source string can be specified. PROGRAM DEMO; VAR STR1,STR2 : STRING; BEGIN STR1 := 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'; WRITELN( 'TEST 1 :', POS('EF', STR1)); WRITELN( 'TEST 2 :', POS('D', STR1, 8)); STR2 := 'XX XX XX'; WRITELN( 'TEST 3 :', POS(' ',STR2)); WRITELN( 'TEST 4 :', POS('XX', STR2, 2)); END. (* OUTPUT *) TEST 1 : 5 TEST 2 : 0 TEST 3 : 3 TEST 4 : 5 Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -43- 5.17 PRED Format 1 PRED( integer_expression ); Format 2 PRED( character_expression ); The PRED function returns preceding value of an integer or a character expression. For example: the PRED of 'c' is 'b'; the PRED of 98 is 97. Examples: WRITELN( A, PRED(A) ); WRITELN( CH, PRED(CH) ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -44- 5.18 REAL$ Format REAL$( real_expression ); The REAL$ function converts a real_expression to a printable standard format for direct output or further editing. The result is a string of length 22, in the format below: ' +0.12345678901234E+00' Examples: WRITELN( FREQUENCY_FILE; REAL$( CYCLES / MICROSECONDS )); STR := REAL$( VELOCITY / 7.03E-21 ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -45- 5.19 ROUND Format ROUND( real_expression ); ROUND is a standard function which converts a real expression to an integer value. If the real value's fractional part is greater than or equal to 0.5 then the value is rounded up to the next higher integer. If the real value is too large to be converted to integer format, a warning message is issued and the value returned is -32768 if the real expression was negative, otherwise +32767 is returned. Examples: INT := ROUND( X + Y ); TEMPERATURE := ROUND( THERMOMETER_READING ); PLOT_X := ROUND( X / SCALING_FACTOR ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -46- 5.20 SEARCH Search is an external function which allows high speed searches of tables. The array of records to be searched can be any length, the offset to the key within the record can be specified, and the key length can be specified. Search takes four arguments: the array, the key, the number of records in the array, and the search parameter record. The count of records in the array is passed by value. The three other arguments are passed by reference. Declaration required to use SEARCH: TYPE search_param = RECORD search_mode : integer; (* must be zero *) record_length : integer; key_offset : integer; key_length : integer; END; record_type = RECORD (* whatever is appropriate *) END; record_array = ARRAY[1..whatever] of record_type; key_type = STRING or ARRAY[1..x] OF CHAR; VAR arr : record_array; key : key_type; parameters : search_param; FUNCTION SEARCH ( VAR arr : record_array ; VAR key : key_type ; count : INTEGER; VAR param : search_param ) ; EXTERN; Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -47- Using SEARCH Set up the search parameter block (generally just once) : parameters.search_mode := 0; parameters.record_length := (* whatever *); parameters.offset := 0 (* or whatever *); parameters.key_length := (* whatever *); SEARCH looks through an array of records for an exact match between the search key and the key within the records. The search_mode option is provided for future extensions to allow the array to be in sorted order, to return the closest record, to let the array to be searched be a linked list, or for the record to contain a pointer to the key. SEARCH returns -1 if the arguments are invalid, 0 if the key cannot be found, and the index record if the key can be found ( starting at 1). Example For example, assume an array of records containing an integer index and a 6-character key: (* type declaration *) search_param = RECORD search_mode : integer; (* must be zero *) record_length : integer; key_offset : integer; key_length : integer; END; char6 = ARRAY[1..6] OF CHAR; record_type = RECORD index_val : INTEGER; key : char6; record_array = ARRAY[1..999] OF record_type; key_type = char6; (* variables *) arr : record_array; key : key_type; parameters : search_param; nr_records : INTEGER; (* number of records *) Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -48- FUNCTION SEARCH (VAR arr : record_array ; VAR key : key_type ; count : INTEGER ; VAR param : search_param ) ; EXTERN; (* setup *) parameter.mode := 0; parameter.record_length := 8; parameter.key_offset := 2; parameter.key_length := 6; (* build an array of keys and indices into arr *) (* keep track of number of records in nr_records *) (* use *) ind := search ( arr, key, nr_records, parameter ); if (ind <= 0) then writeln('Record not found: ', key) else begin (* ... *) end; Record lengths and offsets Record lengths and offsets can be determined by counting bytes. Characters take 1 byte, integers, boolean, and enumerated types take 2 bytes, and real numbers take 8 bytes. Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -49- 5.21 SIN Format SIN( real_expression ); The SIN standard function returns the sine of a real expression in radians. This is implemented as an external function. The declaration for an external function must be included in programs which reference it. FUNCTION SIN ( X : REAL ): REAL; EXTERN; Examples: WRITELN( SIN( ANGLE )); NODE.SINE := SIN( N ); WRITELN( SIN( VELOCITY / CHARGE )); NOTE: See the note included with the COS builtin function for an example using degrees. Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -50- 5.22 SQR Format 1 SQR( real_expression ); Format 2 SQR( integer_expression ); The SQR standard function returns either a real value or an integer value depending on the parameter type. This function returns the square of the parameter expression - the value multiplied by itself. Examples: WRITELN( 'SQUARE OF X IS ', SQR(X) ); AREA := SQR( SIDE ); CIRCLE_AREA := PI * SQR( RADIUS ); ENERGY := MASS * SQR( LIGHT_SPEED ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -51- 5.23 SQRT Format SQRT( real_expression ); This standard function returns the square root of a real expression. This is implemented as an external function. The declaration for an external function must be included in programs which reference it. FUNCTION SQRT ( X : REAL ): REAL; EXTERN; Examples: WRITELN( SQRT( A + 3.14159 )); NODE.VALUE := OLD_NODE.VALUE + SQRT( V ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -52- 5.24 SUCC Format 1 SUCC( integer_expression ); Format 2 SUCC( character_expression ); The SUCC function returns succeeding value of an integer or a character expression. For example: the SUCC of 'b' is 'c'; the SUCC of 97 is 98. Examples: WRITELN( A, SUCC(A) ); WRITELN( CH, SUCC(CH) ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -53- 5.25 TRUNC Format TRUNC( real_expression ); TRUNC is a standard function which converts a real expression to an integer value. The fractional portion of the real expression is truncated. If the real value is too large to be converted to integer format, a warning message is issued and the value returned is -32768 if the real expression was negative, otherwise +32767 is returned. Examples: INT := TRUNC( X + Y ); TEMPERATURE := TRUNC( THERMOMETER_READING ); PLOT_X := TRUNC( X / SCALING_FACTOR ); Copy compliments of Merle Schnick SECTION 5: Builtin Functions JRT Pascal User's Guide version 3.0 NOT FOR SALE -54- 5.26 UPCASE Format UPCASE( string_expression ); The UPCASE function converts a string expression to all upper case letters. Non-alphabetic characters are not changed. Examples: IF UPCASE( COMMAND ) = 'X' THEN CMD_X; WRITELN ( F1; UPCASE( NAME ) ); READLN( OPTION ); IF UPCASE( OPTION ) = 'EXIT' THEN GOTO 99; Copy compliments of Merle Schnick SECTION 5: Builtin Functions  READLN( OPTION ); IF UPCASE( OPTION ) = 'EXIT' THEN GOTO 99; Copy compliments of Merle Schnick SECTION 5: Bui