10/7/13

The Pascal Library

The Pascal Library

In the last chapter, we described the standard library subprograms related to I/O. In this chapter, we will deal with other commonly used subprograms. Note that the HELP facility can also give information on most of these subprograms.

Conversion Functions
The following functions convert one type of data to another.
r o u n d ( x )

This converts a r e a lexpression xinto an i n t e g e rvalue by rounding it up or down to the nearest integer. Therefore, r o u n d ( 3 . 2 )has the value 3while r o u n d ( 3 . 7 )has the value 4 .r o u n d ( 3 . 2 )has the value 3 while r o u n d ( 3 . 7 )has the value 4 .
t r u n c ( x )

This converts a r e a lexpression xinto an i n t e g e rvalue by truncating the fractional part. Therefore the expressions t r u n c ( 3 . 2 )and t r u n c ( 3 . 7 )both have the value 3 .t r u n c ( 3 . 2 )and t r u n c ( 3 . 7 )both have the value 3 .
c h r ( i )

This converts an i n t e g e rexpression iinto a c h a rvalue. The integer is converted to whatever character has the same ASCII representation. This means that the integer must lie inside the values for the ASCII character set, in this case 0to 2 5 5 .
o r d ( c )

This converts a scalar type expression into an integer. c h a rvalues are translated into the integer that has the same ASCII representation. This means that for any c h a rvalue c ,
c h r (o r d ( c ) )equals c

The effect of o r don enumerated types was described in Chapter 3. The o r dfunction is a non-standard function because its arguments can have any scalar type. For this reason, it cannot be passed as an function argument to another subprogram.
F r a c ( x )

This returns a real number whose value is the fractional part of the real value x. For example,
n: =F r a c ( 7 . 3 ) ;
www.templetons.com/brad/alice/language/language8.html 1/19

10/7/13

The Pascal Library

will cause n to have the value 0.3. This comes from Turbo Pascal.
I n t ( x )

This returns a real number whose value is the integer part of the real value x. For example,
n: =I n t ( 8 . 3 ) ;

will cause n to have the value 8.0. This comes from Turbo Pascal.
H i ( n u m ) ;

This routine returns the high-order byte of the integer argument. For example,
i: =H i ( $ 1 2 3 4 ) ;

would set ito be $12. [Found in T U R B O L I B . A P ]

L o ( n u m ) ;

This routine returns the low-order byte of the integer argument. For example,
i: =L o ( $ 1 2 3 4 ) ;

would set ito be $34. {TLIB{

S w a p ( v a r i a b l e ) ;

This function returns an integer whose high and low bytes are reversed from those of the v a r i a b l eargument. For example,
i: =S w a p ( $ 1 2 3 4 ) ;

will result in ihaving the value $3412. [Found in T U R B O L I B . A P ]

Mathematical Functions
Pascal supports most of the basic mathematical functions.
a b s ( x )

returns the absolute value of x . xmay be r e a lor i n t e g e r , and the result will have the same type as the argument.
o d d ( x )

returns t r u eif xis an odd integer, and f a l s eif xis even. xmust be an integer.
www.templetons.com/brad/alice/language/language8.html 2/19

10/7/13

The Pascal Library

s q r ( x )

returns the square of x . xmay be r e a lor i n t e g e r , and the result will have the same type as the argument.
s q r t ( x )

returns the square root of x . xmay be r e a lor i n t e g e r . The result is always r e a l .

s i n ( x )

returns the sine of x . xmay be r e a lor i n t e g e r , and gives an angle in radians. The result is always r e a l .
c o s ( x )

returns the cosine of x . xmay be r e a lor i n t e g e r , and gives an angle in radians. The result is always r e a l .
a r c t a n ( x )

returns the arctangent of x . xmay be r e a lor i n t e g e r . The result is always r e a l , and gives an angle in radians.
l n ( x )

returns the natural logarithm of x(base e ). xmay be r e a lor i n t e g e r . The result is always r e a l .
e x p ( x )

returns the number eto the power x . xmay be r e a lor i n t e g e r . The result is always r e a l . The functions a b sand s q rare non-standard, in that they may return either an integer or real number. For this reason, they may not be passed as function arguments to subprograms.

Order Functions
Order functions can be applied to any scalar type. The ``successor'' function s u c chas the form
n e x t: =s u c c ( v a l u e ) ;

where v a l u eis any scalar value. The result returned by s u c cis the next value in the scalar type. For example, if v a l u eis an integer, s u c creturns the next integer, so
s u c c ( 3 )=4

If v a l u eis an enumerated type, s u c creturns the next value in the enumerated list. Thus if you define
t y p e d a y s=( s u n , m o n , t u e , w e d , t h u , f r i , s a t ) ;

you would have

www.templetons.com/brad/alice/language/language8.html 3/19

10/7/13

The Pascal Library

s u c c ( s u n )=m o n s u c c ( m o n )=t u e {A n ds oo n}

If you try
s u c c ( s a t )

you will be given an error message. s a tis the last element in the enumerated type and has no successor. The ``predecessor'' function p r e dis the converse of s u c c . It has the form
p r e v i o u s: =p r e d ( v a l u e ) ; p r e dreturns whatever comes before the given v a l u e . For example, s u c c ( 3 )=2 s u c c ( t u e )=m o n

If v a l u ehas no predecessor, Alice will give you an error.

Packing Functions
Other implementations of Pascal have functions named p a c kand u n p a c k .p a c ktakes the values that are stored in a normal array and assigns them one by one to a packed array. u n p a c ktakes the values that are stored in a packed array and assigns them one by one to a normal array. Alice recognizes the names p a c kand u n p a c k , but the subprograms just give an error if called.

Dynamic Memory Allocation

The n e wprocedure can be used to allocate memory dynamically at execution time. The memory is allocated from a store of memory called the heap. The simplest form of n e wis
n e w ( p ) ;

where pis a pointer variable. The procedure will allocate sufficient memory space to contain the sort of data that ppoints to. For example, if pis declared
v a r p:^ i n t e g e r ; n e wwill obtain enough space to

hold an integer. If pis a pointer to some record type, n e wwill allocate enough space to hold a record of that type. When the space has been obtained, n e wwill set up pto point at the space that has been obtained.

As a simple example, the following code uses n e wto set up a linked list of records.
www.templetons.com/brad/alice/language/language8.html 4/19

10/7/13

The Pascal Library

t y p e l i s t p t r=^ l i s t e l e m e n t ; l i s t e l e m e n t=r e c o r d l i n k:l i s t p t r ; o t h e r:{ V a r i o u st h i n g s } ; e n d ; v a r r o o t ,p l:l i s t p t r ; b e g i n { G e tr o o to fl i s t } n e w ( r o o t ) ; p l: =r o o t ; f o ri: =1t o1 0d ob e g i n n e w ( p l ^ . l i n k ) ; p l: =p l ^ . l i n k ; e n d ; p l ^ . l i n k: =n i l ; { A n ds oo n }

This allocates 1 0new list elements and links them together in a linked list. Note that n e wis one of the few ways to initialize a pointer. All the other ways involve calls to Pointer functions (described later in this chapter). A second form of n e wis used when allocating space for records with variant fields. This has the form
n e w ( p , t 1 , t 2 , . . . ) ;

where pis a pointer to the record type, and t 1 , t 2 , . . .are values for one or more tag fields of the variant part. By plugging these values into the various tag-fields, n e wcan determine the correct amount of memory to allocate. Note that n e wdoes not put these values into the tag-fields of the record it creates; it simply uses these values to determine how big the record should be. If n e wis not supplied with enough tag-fields to totally determine the size of memory required, it will allocate enough memory to hold the largest possible record of this type. Alice ignores the tag fields and always does this. The d i s p o s eprocedure is used to release memory that has been allocated through n e w .d i s p o s eshould be called with the same arguments that were passed to the n e wprocedure that allocated the memory. Therefore you should use
d i s p o s e ( p ) ; d i s p o s e ( p , t 1 , t 2 , . . . ) ;

This is the only way that memory allocated by n e wmay be freed up. In particular, memory allocated inside a subprogram is not automatically released when the subprogram terminates. You must release the memory explicitly with d i s p o s e . Releasing the memory makes it available for re-allocation in later calls to n e w , but it does not decrease the size of your program. If you call d i s p o s eand give a file variable as an argument, Alice will close the file associated with the variable. The M a r kprocedure is used to find out the current value of the heap pointer. The usage is
M a r k ( v a r i a b l e ) ;
www.templetons.com/brad/alice/language/language8.html 5/19

10/7/13

The Pascal Library

where the v a r i a b l eis a pointer. The R e l e a s eprocedure sets the heap pointer back to a particular value. Its usage is
R e l e a s e ( v a r i a b l e ) ;

where the v a r i a b l eis a pointer. Both M a r kand R e l e a s eare found in T U R B O L I B . A P . They are intended for Turbo Pascal compatibility, and should not be used in new programs; instead, D i s p o s eshould be used. Also note that M a r kand R e l e a s eare not compatible with the N e w /D i s p o s eform of memory allocation. To find out how large a block can be allocated, use the M a x A v a i lfunction. It returns the size of the largest block of contiguous free storage available on the heap. To find out the total amount of free memory, use the M e m A v a i lfunction. It returns the total amount of storage available on the heap. Both M a x A v a i land M e m A v a i lreturn an integer specifying the number of 16-byte units called ``paragraphs.'' The returned value is an integer; if it is less than zero, the actual value can be computed as a real number using the expression MaxAvail + 65536.0, or MemAvail + 65536.0. In the current release of Alice , the values will always be greater than zero. The G e t M e mand F r e e M e mroutines are used to allocate and deallocate dynamic memory blocks of a userspecified size.
G e t M e m ( v a r i a b l e ,n ) ;

will allocate nbytes from the heap and set the pointer v a r i a b l eto point to that block. This is more general than n e w , since it is not limited to allocating just enough space for a particular instance of a variable. The M a x A v a i lfunction can be used to find out in advance if the call to GetMem will succeed or fail.
F r e e M e m ( v a r i a b l e ,n ) ;

will return the memory pointed to by v a r i a b l eto the free pool for subsequent re-allocation. The pointer should be one set by G e t M e m , and the value of nshould match the value in the call to G e t M e m . It is important that you not call F r e e M e mon any pointer not allocated by G e t M e m , and that you not accidentally free the same memory twice. You should also be careful not to keep copies of the pointer from G e t M e min other pointer variables, and then try and refer through them after the memory has been deallocated by F r e e M e m .

String Manipulation Routines

String manipulation routines manipulate string constants and variables with string types. Our descriptions of these routines will give examples of source code using each routine, followed by output from this source code. The first set of functions in this section are taken from Watcom Pascal.
S t r C o n c a t ( s t r 1 , s t r 2 ) ;
www.templetons.com/brad/alice/language/language8.html 6/19

10/7/13

The Pascal Library

This procedure concatenates the contents of s t r 2on the end of s t r 1 .

s t r 1: =' h e l l o ' ; s t r 2: ='t h e r e ' ; S t r C o n c a t ( s t r 1 , s t r 2 ) ; w r i t e l n ( s t r 1 ) ; ----h e l l ot h e r e

Note the string concatenation can also be performed with the ``+'' operator.
S t r D e l e t e ( s t r i n g , N , p o s i t i o n ) ;

This procedure deletes Ncharacters from s t r i n g .P o s i t i o nis an integer giving the subscript of the first character to be deleted.
s t r: =' T h eq u i c kb r o w nf o x ' ; S t r D e l e t e ( s t r , 2 , 5 ) ; w r i t e l n ( s t r ) ; ----T h ei c kb r o w nf o x

This routine is similar to the Turbo Pascal D e l e t eroutine.

S t r I n s e r t ( s t r 1 , s t r 2 , N ) ;

This procedure inserts the contents of s t r 2into s t r 1 . The first character of s t r 2will become character N of s t r 1 .
s t r: =' T h eq u i c kf o x ' ; S t r I n s e r t ( s t r 1 , ' b r o w n ' , 5 ) ; w r i t e l n ( s t r ) ; ----T h eb r o w n q u i c kf o x

This routine is similar to the Turbo Pascal I n s e r troutine.

i: =S t r L e n ( s t r i n g ) ;

This function returns an integer giving the length of a string. For a string constant, this is the number of characters in the constant. For a string variable, it is the number of characters currently stored in the variable. If the variable is not full, it will be the number of characters up to but not including the S t r E n dthat follows the last character in the string.
s t r: =' a b c d e f ' ; w r i t e l n ( S t r L e n ( s t r ) ) ; s t r: =' a b c ' ; w r i t e l n ( S t r L e n ( s t r ) ) ; w r i t e l n ( S t r L e n ( ' x y z ' ) ; ----6 3
www.templetons.com/brad/alice/language/language8.html 7/19

10/7/13

The Pascal Library

This routine is similar to the Turbo Pascal L e n g t hroutine.

i: =S t r S c a n ( s t r 1 , s t r 2 ) ;

This function looks for the string s t r 2inside s t r 1 . If it is found, S t r S c a nreturns the subscript where s t r 2 begins in s t r 1 . If the string is not found, S t r S c a nreturns 0.
i: =S t r S c a n ( ' h e l l ot h e r e ' , ' t h e ' ) ; w r i t e l n ( i ) ; ----7

This routine is similar to the Turbo Pascal P o sroutine.

i: =S t r S i z e ( s t r i n g ) ;

This function returns an integer giving the maximum length of a string. If the string is a string constant, this is the number of characters in the string. If the string is a string variable, this is the maximum number of characters that the string can hold, regardless of how many it holds at the moment.
v a r s t r:p a c k e da r r a y[ 1 . . 1 0 ]o fc h a r ; . . . w r i t e l n ( S t r S i z e ( ' a b c ' ) ) ; s t r: =' a b c ' ; w r i t e l n ( S t r S i z e ( s t r ) ) ; ----3 1 0 S u b S t r ( s t r 1 , N , p o s i t i o n , s t r 2 ) ;

This procedure obtains a copy of part of s t r 1 . Nis the length of the substring and p o s i t i o nis the subscript where the substring starts. The substring that is obtained is copied into s t r 2 .
s t r 1: =' H e l l ot h e r e ' ; S u b S t r ( s t r 1 , 2 , 3 , s t r 2 ) ; w r i t e l n ( s t r 2 ) ; ----l l

Also of note for this purpose is the Turbo Pascal C o p yfunction. The remaining functions in this section are taken from Turbo Pascal.
D e l e t e ( s t r ,p o s ,n u m ) ;

This procedure deletes a substring of length n u mstarting at position p o sin the string variable s t r . The remaining characters (if any) in the string are shifted left. This routine is similar to the Watcom StrDelete routine.
www.templetons.com/brad/alice/language/language8.html 8/19

10/7/13

The Pascal Library

I n s e r t ( s r c ,d e s t ,p o s ) ;

This procedure inserts the string s r cinto the string d e s tat position p o s . The variables s r cand d e s tare both of type string; pos is of type integer. An error message will be issued if the p o sis past the end of the string, or the string becomes too long. This is stricter error checking than that provided by the same routine in the Turbo Pascal compiler. This routine is similar to the Watcom StrInsert routine.
C o p y ( s t r ,p o s ,n u m ) ;

This function returns a substring of the string variable s t rof length n u mstarting at position p o s . It returns the null string (i.e. a string of length zero) if pos is greater than the length of the string.
L e n g t h ( s t r )

This function returns the length of the string argument in characters. For a string constant, this is the number of characters in the constant. For a string variable, it is the number of characters currently stored in the variable. Length gets its value from the special length byte kept at the zeroth index of every string. It is similar to the Watcom Strlen function.
P o s ( s r c h ,s t r ) ;

This function returns the position in the string s t rat which the string s r c his found. It returns 0 if s r c hwas not found in s t r . For example,
i: =P o s ( ' e x e c ' ,' a u t o e x e c . b a t ' ) ;

will cause i to have the value 5, while

i: =P o s ( ' g r e m l i n ' ,' h a l l o w e e n ' ) ;

will cause i to have the value 0. This is similar to S t r S c a n

S t r ( v a l ,s t r )

This procedure puts the value of the given variable v a l(which may be integer or real) into the given string variable s t ras an ASCII representation of the number. The variable v a lcan actually have format specifiers of the same type found in w r i t eprocedure calls. One can specify a field width for integers and reals. Reals may also have a precision field, just as with w r i t e . In general
S t r ( i : n ,d e s t ) ; w r i t e l n ( d e s t ) ;

is the same as:

w r i t e l n ( i:n ) ;

if d e s tis a string large enough to hold the written number. Note that Alice places a space in front of integer operands if no field width is provided. A field width of zero www.templetons.com/brad/alice/language/language8.html eliminates this. This space is not output when Borland deviations (+b) are enabled.

9/19

10/7/13

The Pascal Library

eliminates this. This space is not output when Borland deviations (+b) are enabled. An error occurs if the string is not large enough to hold the number.
V a l ( s t r ,v a r i a b l e ,c o d e ) ;

This procedure is the inverse of the s t rprocedure; it examines the string contained in s t rand converts it to a number which it stores in v a r . The type of the number is either real or integer, depending on the type of v a r . Leading and trailing spaces are not permitted; the valid formats for the number are the same as those for constants in Alice Pascal. In addition, real numbers with nothing before the decimal point (e.g. ".1") are acceptable. If the conversion is successful, the integer variable c o d eis set to zero; otherwise, it contains an index into s t rof the character on which the conversion failed. If this is the case, the value of v a ris undefined. For example,
V a l ( ' 7 . 8 ' ,n ,s t a t ) ;

will set nto 7.8 and s t a tto zero, while

V a l ( ' 7 y 2 ' ,n ,s t a t ) ;

will result in s t a tbeing 2 (the index of the letter y in the string) and the value of nwill be undefined.
U p C a s e ( c ) ;

This function returns a character which is the upper-case equivalent of the character c . For example,
c h: =U p C a s e ( ' b ' ) ;

will result in c hhaving the value 'B'. This routine is handy if you want to accept user input in either upper or lower case.

Pointer Functions
There are a variety of routines that deal with addresses and pointers. Most of these use values of the P o i n t e r type, the special Alice built in type that is assignment compatible with all other pointers.
i: =a d d r e s s ( v a r i a b l e ) ;

This function obtains the actual memory address of its argument. The argument must be a variable name, a subscripted variable, a field inside a record variable, or an indirectly-referenced variable. a d d r e s sreturns an integer that gives the machine address that has been allocated to that variable. If a machine address does not fit in an integer, as is the case with the 8086 processor in the IBM-PC, the result returned is actually only part of the address, namely the offset . For example,
i: =a d d r e s s ( v ) ;
www.templetons.com/brad/alice/language/language8.html 10/19

10/7/13

The Pascal Library

obtains the integer offset of the variable v . You can also specify a second argument for a d d r e s s , indicating whether you want the segment containing the variable or the offset of the variable within the segment. If the argument is the integer 0 , you get the offset; if it is any other integer, you get the segment. If this second argument is omitted, a d d r e s sreturns the offset. For example,
i: =a d d r e s s ( v , 1 ) ;

obtains the segment that contains the variable v .

a d d r e s sis unique to

Alice .

i: =O f s ( v a r i a b l e ) ;

This function is similar to a d d r e s s , except that it does not take a second argument and always returns the offset. [Found in T U R B O L I B . A P ]
p: =M a k e P o i n t e r ( v a r i a b l e ) ;

This function is much like a d d r e s sexcept that it returns a P o i n t e rtype value instead of an integer. This can be assigned to any valid Pascal pointer type. M a k e P o i n t e ris unique to Alice . Unlike a d d r e s s ,M a k e P o i n t e r does not need to deal with offsets and segments, as a variable of P o i n t e rtype always holds a pointer. Note, however, that in SMALL model Alice , such pointers may only point within Alice 's 64K data segment.
p: =A d d r ( v a r i a b l e ) ;

This is Turbo Pascal's version of M a k e p o i n t e r . It returns a pointer to the given variable. For example,
v a r i:^ i n t e g e r ; . . . i: =A d d r ( v ) ; i ^: =1 0

Places 10 (indirectly) into v , assuming it is an integer variable. [Found in T U R B O L I B . A P ]

p: =R a w P o i n t e r ( o f f s e t , s e g m e n t ) ;

This function converts an integer address into a Pointer type. As such, it is the inverse of a d d r e s s . The o f f s e t argument is an integer giving an offset within a segment, and the optional s e g m e n targument is an integer giving a segment number. If not provided, the second argument is assumed to be the Data Segment. In small-model Alice , this segment number must either be omitted or equal to the Data Segment (Dseg). The value returned by R a w P o i n t e rhas the P o i n t e rtype. R a w P o i n t e ris unique to Alice .
p: =P t r ( s e g m e n t ,o f f s e t ) ;
www.templetons.com/brad/alice/language/language8.html 11/19

10/7/13

The Pascal Library

This function creates a pointer from two integers, and is the Turbo Pascal equivalent of R a w P o i n t e r . None of the parameters are optional, and in SMALL model Alice , the first parameter must be equal to the Data Segment as returned by D S e g .
i: =p e e k ( a d d r e s s ) ;

This function returns the value that is at the given memory address. The a d d r e s sargument is given as an integer. The value that is returned is a single byte and will therefore be in the range 0..255. On the IBM PC, only the first 64K of physical memory may be accessed this way. This 64K is not the Data Segment of Alice . To access other addresses, use M e m _ T o _ V a r(described below).
p o k e ( a d d r e s s , v a l u e ) ;

This procedure stores a value in the given address. The a d d r e s sis given as an integer. Since p o k eonly stores a single byte, the v a l u eargument should be in the range 0..255. If it is not, p o k ewill use v a l u em o d2 5 6 . On the IBM PC, only the first 64K of physical memory may be accessed this way. This is not the Data Segment used by Alice . To access other addresses, use V a r _ T o _ M e m(described below).
V a r _ T o _ M e m ( v a r i a b l e , o f f s e t , s e g m e n t )

This routine copies a variable to an absolute address in memory. On an IBM-PC, this address is specified with two integers, an offset and a segment. Great care should be taken when using this routine, as writing improperly on absolute memory can easily crash your machine. The segment argument is optional, and defaults to the Data Segment. Be warned when writing into the Data Segment that this routine does not mark the memory it touches as initialized.
M e m _ T o _ V a r

This routine copies from absolute memory into the specified variable. It is the inverse of V a r _ T o _ M e m . On an IBM-PC, the address is specified with two integers providing the offset and segment of the desired memory location. The number of bytes copied equals the size of the variable in question.
M o v e ( s r c ,d e s t ,c o u n t )

This procedure copies a number of bytes specified by the integer c o u n tfrom the location of the variable specified by s r cto the location of the variable specified by d e s t . Both s r cand d e s tmay be of any type. It is up to you to make sure there is enough room in d e s tto contain the data. See also V a rT oM e mand M e mT o V a r . This routine is contained in T U R B O L I B . A P .
F i l l C h a r ( v a r i a b l e ,n u m ,v a l u e )

This procedure fills memory with the given character v a l u e , starting at the base address of the specified v a r i a b l e , for a length of n u mcharacters. The v a rcan be of any type; n u mmust be an integer, and the v a l u e must be a c h a r a c t e ror b y t e . This routine is very fast (much faster than doing it yourself in a loop). It is up to you to make sure that there is
www.templetons.com/brad/alice/language/language8.html

enough room in the variable to contain the data.

12/19

10/7/13

The Pascal Library

enough room in the variable to contain the data. Note that strings have a length byte in the zeroth position; this byte will get overwritten if you pass a string to F i l l C h a r . This routine is contained in T U R B O L I B . A P .
i: =D s e g ;

This function returns the value of the Data Segment as an integer. In small model Alice , this is the segment in which all variables are found. When constructing pointers (for example, using p t r ), you should use the value of d s e g . This routine is contained in T U R B O L I B . A P .
i: =C s e g ;

This function returns the value of the Code Segment as an integer. This value should almost never be used for anything, since Alice is an interpreter. (For more information about the differences between interpreters and compilers, refer to the section on converting between Turbo and Alice ). The Cseg function returns the value of one of the code segments of the Alice interpreter. Any offsets into the Cseg that the program uses will be meaningless; also, using Cseg in the setting of interrupt vectors is incorrect. This routine is contained in T U R B O L I B . A P .
i: =S s e g ;

This function returns the value of the Stack Segment as an integer. In small model Alice , this is the same as the Data Segment. This routine is contained in T U R B O L I B . A P .
i: =S e g ( v a r i a b l e ) ;

This function returns the segment address of the given variable. In small model Alice , this will always be the same as the program's data segment (i.e., d s e g ). This routine is found in T U R B O L I B . A P .

Random Number Generation

Alice includes a function called r a n d o mthat generates pseudo-random numbers. Unfortunately, maintaining compatiblity with both Watcom and Turbo Pascals is impossible with this function, so two versions exist. When Turbo Pascal features are disabled with the ``t '' option, r a n d o macts as it does in Alice 1.2 and Watcom Pascal. Otherwise it acts as the r a n d o mfunction of Turbo Pascal. For both systems,
i n i t r a n d o m ( s e e d , u p p e r ) ;

initializes a pseudo-random number generator. Both s e e dand u p p e rare integers. Different values of s e e dwill give different number sequences; identical values of s e e dwill give identical sequences. When using Alice 1.2/Watcom random numbers, these will be generated in the range 0 . . ( u p p e r 1 ) .
www.templetons.com/brad/alice/language/language8.html 13/19

10/7/13

The Pascal Library

The actual random numbers are obtained from a function named r a n d o m . If you disable Turbo Pascal compatibility by invoking ALICE with the toption, the call to r a n d o mhas the form
i: =r a n d o m ;

This returns a pseudo-random integer. You may not call r a n d o muntil you have initialized the random number generator with i n i t r a n d o m . If you do not disable Turbo Pascal features, the call to r a n d o mhas the form
i: =r a n d o m ( N ) ;

where Nis an integer. This generates a pseudo-random integer in the range 0 . . N 1 . In this case, you do not have to call i n i t r a n d o mfirst. If you omit the Nas in
a: =r a n d o m ;

the function will return a pseudo-random r e a lnumber that is strictly less than 1 . 0and greater than or equal to 0 . 0 .
R a n d o m i z e ;

This procedure re-seeds the random number generator from the system clock, so that a different sequence of values will be produced for every run. [Found in T U R B O L I B . A P ]

System Calls
The following routines let you perform system calls. Users should normally never need to use these.
i: =S y s F u n c ( p , a r g , a r g , a r g , . . . ) ;

This function calls a system function. The pargument is a P o i n t e rtype pointing to the memory location of the function to be called. The function is passed (in Microsoft C calling style) an itneger argument count and pointers to the top and bottom of a vector of arguments. The value returned by S y s F u n cis the value returned by the system function. S y s F u n ccomes from Watcom Pascal, but is not compatible with it on the IBM-PC.
S y s P r o c ( p , a r g , a r g , a r g , . . . ) ;

This procedure works the same way as S y s F u n c . It is used to call system routines that do not return a value. S y s P r o ccomes from Watcom Pascal, but is not compatible with it on the IBM-PC.

Internal C Routines
The following routines all make calls to a special internal library of useful routines contained in Alice . These routines are not intended for general users, and no guarantees are made they they will remain the same from one Alice release to the next. The Alice distribution disks come with Pascal library routines that make use of these internal features. To be safe, make use of the libraries instead of calling these ``CProcs'' directly. These routines are all unique to Alice .
www.templetons.com/brad/alice/language/language8.html 14/19

10/7/13

The Pascal Library

i: =C I n t F u n c ( a r g s ) ;

calls a C function that returns an integer. For more information, see the Alice User Guide.
l: =C L o n g F u n c ( a r g s ) ;

calls a C function that returns a long integer. C L o n g F u n cactually returns a pointer to this long integer. The long integer is expressed as a record with two integer fields named l o wand h i g h . These contain the two halves of the long integer. For more information, see the Alice User Guide.
p: =C P t r F u n c ( a r g s ) ;

calls a C function that returns a pointer. For more information, see the Alice User Guide.
C P r o c ( a r g s ) ;

calls a C function that does not returns a value. For more information, see the Alice User Guide.
p: =S y s P o i n t e r ( i ) ;

returns the value of an Alice control variable. For more information, see the Alice User Guide. S y s P o i n t e ris unique to Alice .

Outside World Interface

C h a i n ( f i l e n a m e ) ;

runs the Alice program contained in the specified file. There is a similar routine in Turbo Pascal; however, it is not the same. Turbo's Chain routine only runs special Turbo chain files, and preserves variables from one program to the other. In Alice , the c h a i nroutine will erase the current program, and load and run the new one. This is found in the Useful DOS routines library.
E x e c u t e ( f i l e n a m e ) ;

This routine executes a DOS program in the same way that the Alice D O Scommand does. The command is executed, and control is returned to the running Alice program when it terminates. The ``COMMAND.COM'' shell program is not used, so commands built into it like ``DIR'' and ``COPY'' may not be used directly. Note that sufficient memory must be available to execute the command at the same time as Alice . This is found in the Useful DOS routines library.

File and Directory Handling Routines

C h D i r ( p a t h ) ;

This routine changes the DOS current directory to the specified path. If the string includes a leading drive specifier, the current drive is changed as well. For example,
www.templetons.com/brad/alice/language/language8.html 15/19

10/7/13

The Pascal Library

C h D i r ( ' c : \ d a t a ' ) ;

will set the current drive to be C:, and the current directory to be the \data directory on that drive. If you change directories, any relative pathnames (i.e. pathnames that are not completely specified from the root directory down) will no longer be valid. In particular, this applies to the save file name. This routine is contained in T U R B O L I B . A P .
E r a s e ( f i l e n a m e ) ;

This procedure erases the specified file from the disk. It is important that you do not erase a file that is currently active (that is, opened using r e s e tor r e w r i t eor a p p e n d ). This routine is contained in T U R B O L I B . A P .
G e t D i r ( d r i v e ,s t r i n g v a r ) ;

This procedure stores into the specified string variable the current directory for the specified drive. The drive is an integer, 1 for A:, 2 for B: and so on. If drive is 0, the current drive is assumed. For example,
G e t D i r ( 3 ,c u r r d i r ) ;

will store into the string variable currdir the current directory for drive C:. A typical directory string would be '\data\first'. If the current directory for the specified drive is the root directory, the string variable will contain the null string (i.e. StrLen(currdir) will be zero). This routine is contained in T U R B O L I B . A P .
M k D i r ( p a t h ) ;

This procedure creates a new directory on the disk, whose name is contained in the string argument p a t h . This new directory is always created on the current drive. For more information on directories, see the DOS manual.
R m D i r ( p a t h ) ;

This procedure removes (i.e., erases) a directory from the disk. You cannot remove a directory that contains files or other directories. Refer to the DOS manuals for more information about directory handling. This routine is contained in T U R B O L I B . A P .
R e n a m e ( o l d p a t h ,n e w n a m e ) ;

This routine changes the name of a file or directory on disk. o l d p a t hspecifies the name (and optional path) of the file or directory to be renamed, and n e w n a m econtains the new name. This routine is contained in T U R B O L I B . A P .

Miscellaneous Routines
p a u s e ;

www.templetons.com/brad/alice/language/language8.html

16/19

10/7/13

The Pascal Library

When Alice has ``Debug On'' and it encounters a call to the p a u s eprocedure, the effect is the same as if a breakpoint was triggered while running the program. The program will stop and wait for run-time commands (e.g. going into immediate mode). When Alice has ``Debug Off'', the p a u s eprocedure has no effect. If you give p a u s ean argument (as in p a u s e ( 1 ) ), the program will pause regardless of whether Debug is On or Off. p a u s e comes from Watcom Pascal.
i: =S i z e O f ( v a r i a b l e ) ;

This function returns the number of bytes of storage that are allocated to a particular variable. With string variables, S i z e O fis equivalent to S t r S i z e+2 .S i z e O fis found both in Alice and Turbo Pascal, but the Alice version does not allow a type as an argument (i.e. SizeOf(integer) is invalid).
D e l a y ( n )

This procedure simply delays for nmilliseconds, where n is an integer. The system clock "ticks" every 55 milliseconds, and this limits the accuracy of d e l a y . Note that the system clocks on all members of the PC family run at the same speed, so a call to d e l a ywill produce a consistent delay regardless of whether it's running on a PC, an XT or an AT. You can use the break key to stop the delay and interrupt the execution of your program.
H a l t ( n ) ;

The h a l troutine will terminate your program and return to Alice . The argument is optional; in the Turbo Pascal version of this routine, the argument is the "return value" or "error level" or "exit status" of the program that is passed back to DOS.
I n t r ( i n t n u m ,r e g r e c ) ;

This procedure generates a software interrupt of type i n t n u m(an integer) and transfers register values into and out of the interrupt routine using the record r e g r e c . The variable r e g r e cshould be declared as follows:
t y p er e g s=r e c o r d A X , B X , C X , D X , B P , S I , D I , D S , E S , F l a g s:I n t e g e r ; e n d ; v a r r e g r e c:r e g s ;

The various register fields should be set to whatever values the registers ought to contain at the time the software interrupt is issued; when the I n t rprocedure returns, the various fields of the record will hold the register contents as of the completion of the interrupt. The F l a g sfield may be read from, but its value is not used to change the actual hardware flags register. It is important that the full record be used, not a shorter version of it, since the routine that copies the hardware registers into the r e g r e crecord assume the full record is available. Use of I n t rshould be avoided, since there are higher-level functions for almost everything.
www.templetons.com/brad/alice/language/language8.html 17/19

10/7/13

The Pascal Library

M s D o s ( r e g r e c ) ;

This procedure executes the software interrupt that interfaces to the MSDOS operating system. It is equivalent to I n t r ( $ 2 1 ,r e g r e c ) . It transfers register values into and out of the MSDOS call using the record r e g r e c . The variable r e g r e cshould be declared as follows:
t y p er e g s=r e c o r d A X , B X , C X , D X , B P , S I , D I , D S , E S , F l a g s:I n t e g e r ; e n d ; v a rr e g r e c:r e g s ;

The various register fields should be set to whatever values the registers ought to contain at the time that MSDOS is called; when the M s D o sprocedure returns, the various fields of the record will hold the register contents as of the completion of the call to MSDOS. The F l a g sfield may be read, but its value is not used to change the actual hardware flags register. It is important that the full record be used, not a shorter version of it, since the routine that copies the hardware registers into the r e g r e crecord assume the full record is available.
T P L i b P r o c ( f i l e n a m e ,o f f s e t ) ; T P L i b F u n c ( f i l e n a m e ,o f f s e t ) ;

These procedures load a binary file from the specified f i l e n a m e(a string constant or constant expression) and execute the routine at the specified (integer) o f f s e tinto that file. The machine language code contained in the binary file must be position independent. Some Turbo Pascal programs (notably those written for version 2.0 of Turbo Pascal) assume only one routine per binary file; in this case, use an offset value of zero. On entry to a routine called in this way, the return address is on top of the stack, and it is always a one-word value (i.e. it is a return address within the current code segment). The routine ends with a RET instruction, which also removes the parameters from the stack. The BP register should be preserved (usually by pushing it, and then transferring the SP register into BP to allow easy access to variables in the stack frame). Restoring SP from BP and then popping BP is a standard way of ending a function. If the routine has additional parameters following it in its call, then the following applies: -V a rtype parameters are passed as long pointers (segment address is higher on the stack than the offset). value parameters generally have their actual values pushed onto the stack - integers, chars, bytes, subranges of integers and booleans will take a single word, with the top byte set to zero for chars and bytes; - real values are stored as six-byte quantities, with the exponent lowest in memory. - strings are stored as the string length, followed by the characters in the string in reverse (i.e. right-to-left) order up into the stack. - sets always occupy 32 bytes (one bit for each member). - pointers are passed much like v a rparameters, with the word containing the segment address higher than the offset. - arrays and records are passed like pointers and v a rparameters.

www.templetons.com/brad/alice/language/language8.html

18/19

10/7/13

The Pascal Library

For functions, the function value is returned in AX for functions returning scalar types other than reals, DX:AX for functions returning pointers, and on the top of the stack for all others. Values passed back on the top of the stack are in the same form as parameters to the function (e.g. reals are six bytes, exponent lowest in memory). These routines are found in T U R B O L I B . A P .

www.templetons.com/brad/alice/language/language8.html

19/19