IMP System Library
If you require information about a particular Routine
or Function then type its name. Otherwise type <RETURN>.
ADDMATRIX
DEFINITION: This routine adds two NxM matrices.
SPEC: %EXTERNALROUTINESPEC ADD MATRIX (%LONGREALARRAYNAME A,B,C, %INTEGER N,M)
CALL: ADD MATRIX (A,B,C,N,M)
A,B,C are the names of three longreal two-dimensional arrays.
Array A contains the matrix sum of matrices in arrays B and C.
Arrays B and C contain the matrices to be added: arrays B and C
are not corrupted.
N,M are the integer expressions whose values give upper bounds for the
dimensions of A, B and C, the lower bounds being taken to be 1.
ERROR CONDITIONS: If the array bounds of any of the matrices are zero or
negative, the program terminates with the message:
MATRIX BOUND ZERO OR NEGATIVE
ADDR
DEFINITION: This integer function gives the absolute address of the %NAME type
parameter specified on entry.
SPEC: Not required
CALL: ADDR(X)
X is the name of a variable whose address is to be returned.
ERROR CONDITIONS: None.
ARCCOS
DEFINITION: This longreal function finds the value of the angle whose cosine is
specified on entry.
SPEC: Not required
CALL: ARCCOS(X)
X is a real or longreal expression.
The value is given in radians, and lies in the range 0 to +
ERROR CONDITIONS: If x is not in the range -1 <= x <= 1, the program terminates
with the message:
ARCCOS ARG OUT OF RANGE
ARCSIN
DEFINITION: This longreal function finds the value of the angle whose sine is
specified on entry.
SPEC: Not required
CALL: ARCSIN(X)
X is a real or longreal expression.
The value is given in radians, and lies in the range - /2 to + /2.
ERROR CONDITIONS: If x is not in the range -1 <= x <= 1, the program terminates
with the message:
ARCSIN ARG OUT OF RANGE
ARCTAN
DEFINITION: This longreal function gives the value of the angle whose tangent is
specified on entry.
SPEC: Not required
CALL: ARCTAN(X,Y)
X,Y are real or longreal expressions.
The value, in radians, of the angle whose tangent is specified by 'y/x'
is returned. This value lies in the range - to + , and is in the first
or fourth quadrant if x > 0, and in the second or third quandrant if x <
0.
ERROR CONDITIONS: If the parameters passed to this routine are both zero the
program terminates with the message:
ARCTAN ARGS ZERO
ARRAY
DEFINITION: This map can be used to map an array onto an area specified by the
address of its start.
SPEC: Not required
CALL: ARRAY(I,J)
I is an integer expression specifying an address
J is the name of an array or an arrayformat
The arrayformat statement is used to describe the characteristics of the
array which is being mapped. As an alternative to using the name of an
arrayformat for the second parameter, the name of another array can be
used, if one with suitable characteristics has been defined in the
program.
In the following example the two-dimensional array ATWO is mapped onto an
array AONE, which is declared as a one-dimensional array:
%INTEGERARRAY AONE (1:10000)
%INTEGERARRAYNAME ATWO
%INTEGERARRAYFORMAT AFORM (1:100,1:100) ; !This statement describes
the
!characteristics of the
array ATWO
ATWO==ARRAY(ADDR(AONE(1)),AFORM)
ATWO(27,27)=928
ERROR CONDITIONS: None.
BITS
DEFINITION: This integer function finds the number of non-zero bits in the
binary representation of a specified integer.
SPEC: %EXTERNALINTEGERFNSPEC BITS (%INTEGER N)
CALL: BITS(N)
N is the integer expression whose binary representation is to be
examined.
ERROR CONDITIONS: None
BYTEINTEGER
DEFINITION: This map enables the user to access a particular byte location whose
address is specified by the parameter.
SPEC: Not required
CALL: BYTE INTEGER(N)
N is an integer expression giving the absolute address in core of
the required location.
This map may be used to access a byte integer location as though it held
a byteinteger value, or to store a byteinteger value at the specified
address:
%INTEGER I
%BYTEINTEGER J
I=X'12345678' ; !I is an integer containing a 4 byte
binary pattern
J=BYTEINTEGER (ADDR(I)+1) ; !J has the value X'34' and I is
unchanged
BYTEINTEGER (ADDR(I)+3)=X'9A' ; !I now contains the binary pattern
X'1234569A' and
!J is unchanged
ERROR CONDITIONS: None.
CHARNO
DEFINITION: This map enables the user to access a character in a specified
position within a string.
SPEC: Not required
CALL: CHARNO(S,N)
S is the name of the string variable containing the string.
N is an integer expression indicating which character of the string
is to be accessed.
ERROR CONDITIONS: In checking mode a bound check occurs but otherwise the result
is undefined unless 1 <= n <= LENGTH(S).
CLOSEDA
DEFINITION: This routine closes the direct access file on the channel specified
on entry.
SPEC: %EXTERNALROUTINESPEC CLOSEDA (%INTEGER N)
CALL: CLOSEDA(N)
N is an integer expression which specifies the channel number and
must be in the the range allowed by the operating system being
used.
The file is closed and may not be used again without re-opening.
ERROR CONDITIONS: If an attempt is made to close a file twice or to close a file
which has been neither opened nor defined, the program terminates with an
appropriate message.
CLOSESQ
DEFINITION: The routine closes the sequential file on the channel specified on
entry.
SPEC: %EXTERNALROUTINESPEC CLOSESQ (%INTEGER M)
CALL: CLOSESQ(M)
M is an integer expression which specifies the channel number and
must be in the range allowed by the operating system being used.
The file is closed and may not be used again without re-opening.
ERROR CONDITIONS: If an attempt is made to close a file twice, or to close a
file which has been neither opened nor defined, the program terminates
with an appropriate message.
CLOSESTREAM
DEFINITION: This routine closes a user-defined stream.
SPEC: Not required
CALL: CLOSE STREAM(N)
N is an integer expression which specifies the stream to be closed.
The stream n is closed such that on the next call of either SELECT INPUT
or SELECT OUTPUT for that stream, the stream is reset to the start. Note
that n must not be the current input or output stream.
ERROR CONDITIONS: If the stream is not defined on entry to the routine, if an
attempt is made to close a stream not in the range allowed by the
operating system being used, or if n is a current stream, then the
program terminates with an appropriate message.
COPYMATRIX
DEFINITION: An NxM matrix is copied from one two-dimensional array onto another.
SPEC: %EXTERNALROUTINESPEC COPY MATRIX(%LONGREALARRAYNAME A,B, %INTEGER N,M)
CALL: COPY MATRIX (A,B,N,M)
A,B are the names of two longreal two-dimensional arrays.
Array A contains a matrix identical to the matrix contained in B.
Array B contains the rectangular matrix which is to be copied:
array B is unchanged.
N,M are the integer expressions whose values give the upper limits for
the dimensions of the given arrays, the lower limits being taken
to be 1.
ERROR CONDITIONS: If n or m is negative or zero, the program terminates with the
message:
MATRIX BOUND ZERO OR NEGATIVE
COS
DEFINITION: This longreal function gives the value of the cosine of the quantity
specified on entry. This quantity must be in radians.
SPEC: Not required
CALL: COS(X)
X is a real or longreal expression.
ERROR CONDITIONS: If the modulus of the argument of this function is greater
than 3.53 x 10 the result would be wholly inaccurate and the program
terminates with the following message:
COS ARG OUT OF RANGE
COT
DEFINITION: This longreal function gives the value of the cotangent of the
quantity specified on entry. This quantity must be in radians.
SPEC: Not required
CALL: COT(X)
X is a real or longreal expression.
ERROR CONDITIONS: If the modulus of the argument of this function is greater
than or equal to 10 the result would be wholly inaccurate and the
program terminates with the message:
COT ARG OUT OF RANGE
If the argument passed to this function is near 0 or a multiple of , the
program terminates with the message:
COT ARG INAPPROPRIATE
CPUTIME
DEFINITION: This longreal function gives the total CPU time used from an
arbitrary starting point.
SPEC: %EXTERNALLONGREALFNSPEC CPUTIME
CALL: CPUTIME
No parameters
The total CPU time used since an arbitrary starting point is returned as
a positive long real number having seconds as its unit of time. Note
that there is a small CPU time overhead in calling the function itself.
ERROR CONDITIONS: None.
DATE
DEFINITION: This string function yields the current date.
SPEC: %EXTERNALSTRINGFNSPEC DATE
CALL: DATE
No parameters.
The date is returned in the form dd/mm/yy, and may be printed out using
PRINTSTRING.
ERROR CONDITIONS: None.
DET
DEFINITION: This longreal function evaluates the determinant of an NxN matrix.
The method of Gaussian elimination with partial pivoting is used. This
is implemented using the routine SOLVE LN EQ.
SPEC: %EXTERNALLONGREALFNSPEC DET (%LONGREALARRAYNAME A, %INTEGER N)
CALL: DET (A,N)
A is the name of a longreal two-dimensional array containing the
square matrix whose determinant is required.
Note that the contents of this matrix are destroyed.
N is the integer expression whose value gives the upper limit for
the dimensions of A, the lower limits taken to be 1.
The value of the determinant is returned. Note that large errors may
occur if the matrix is ill-conditioned, and if this is suspected,
perturbed matrices should be examined.
ERROR CONDITIONS: If the matrix bound n is zero or negative, the program
terminates with the message:
MATRIX BOUND ZERO OR NEGATIVE
DIVMATRIX
DEFINITION: Given an NxN matrix B and an NxM matrix A, the routine generates
INV(B).A, an NxM matrix. Both B and A are destroyed.
SPEC: %EXTERNALROUTINESPEC DIV MATRIX (%LONGREALARRAYNAME A,B, %INTEGER N,M,
%LONGREALNAME DET)
CALL: DIV MATRIX (A,B,N,M,DET)
A,B are the names of two two-dimensional longreal arrays.
Array A contains rectangular matrix A on input.
Array B contains square matrix B on input.
The result of the division is placed in array A and matrix B is
destroyed.
N,M are the integer expressions whose values give the upper limits for
the dimensions of the given arrays, the lower limits being taken
to be 1.
DET is the name of a longreal variable which is set by the routine to
the value of the determinant of the matrix in array B.
Note that large errors may occur if the matrix B is ill-conditioned, and
if this is suspected, perturbed matrices should be examined.
ERROR CONDITIONS: If N or M is less than or equal to zero, the program
terminates with the message:
DIV MATRIX DATA FAULT N = X
where X is the invalid value N or M.
ERFN
DEFINITION: This real or longreal function gives the value of the error function
of the quantity specified on entry.
SPEC: %EXTERNALLONGREALFNSPEC ERFN(%LONGREAL X)
CALL: ERFN(X)
X is a real or longreal expression.
The real or longreal value of the error function
y = du
of the quantity specified by X is returned.
ERROR CONDITIONS: None.
ERFNC
DEFINITION: This real or longreal function gives the value of the complemented
error function of the quantity specified on entry.
SPEC: %EXTERNALLONGREALFNSPEC ERFNC (%LONGREAL X)
CALL: ERFNC(X)
X is a real or longreal expression
The real or longreal value of the complemented error function
y = du
or
y = 1 - erfn(X)
of the quantity specified by X is returned.
ERROR CONDITIONS: None.
EXP
DEFINITION: This real or longreal function gives the value of 'e' raised to the
power of the quantity specified on entry.
SPEC: Not required
CALL: EXP(X)
X is a real or longreal expression.
If the argument of this function is less than -180.218 then zero is
returned.
ERROR CONDITIONS: If the argument of this function is greater than 174.673, the
program terminates with the message:
EXP ARG OUT OF RANGE
EXPTEN
DEFINITION: This real or longreal function gives the value of 10 raised to the
power of the quantity specified on entry.
SPEC: %EXTERNALLONGREALFNSPEC EXPTEN (%LONGREAL X)
CALL: EXPTEN(X)
X is a real or longreal expression.
ERROR CONDITIONS: If the argument of this function is greater than 75.0 then the
program terminates with the message:
EXP ARG OUT OF RANGE
FRACPT
DEFINITION: This longreal function gives the value of the fractional part of the
longreal quantity specified on entry.
SPEC: Not required
CALL: FRAC PT(X)
X is a longreal expression of which the fractional part is to be
returned.
The fractional part of x is returned as a long real. If mod(x) exceeds 2-1,
the value returned is always zero. The fractional part is always
calculated as
x - (largest integer less than or equal to x);
e.g. FRACPT(4.6)=0.6
FRACPT(-4.6)=0.4
ERROR CONDITIONS: None.
FROMSTRING
DEFINITION: This string function extracts characters from a string.
SPEC: Not required
CALL: FROM STRING (S,I,J)
S is the name (of type %STRING of the location in which the string
is stored.
I,J are integer expressions giving the lower and upper boundaries
(inclusive) of the character string to be extracted.
The result is a string of characters extracted from the string contained
in S (from I to J inclusive): s is unchanged.
ERROR CONDITIONS: Unless 1 <= i <= j <= LENGTH(S), the program terminates with
the message:
STRING INSIDE OUT
GAMMAFN
DEFINITION: This longreal function gives the value of the gamma function of the
quantity specified on entry.
SPEC: %EXTERNALLONGREALFNSPEC GAMMAFN(%LONGREAL X)
CALL: GAMMAFN(X)
X is a real or longreal expression
The real or longreal value of the gamma function
of the quantity specified by X is returned.
ERROR CONDITIONS: If mod(x) is less than 1*10 the program will terminate with
the message:
LGAMMA ARG NOT POSITIVE
If x is greater than 57 the program terminates with the message:
LGAMMA ARG TOO LARGE
HYPCOS
DEFINITION: This real or longreal function gives the value of the hyperbolic
cosine of the quantity specified on entry.
SPEC: %EXTERNALLONGREALFNSPEC HYPCOS(%LONGREAL X)
CALL: HYPCOS(X)
X is a real or longreal expression.
The real or longreal value of the hyperbolic cosine
y =
of the quantity specified by X is returned.
ERROR CONDITIONS: If the modulus of x is greater than or equal to 172.694 the
program will terminate with the message:
HYPCOS ARG OUT OF RANGE
HYPSIN
DEFINITION: This real or longreal function gives the values of the hyperbolic
sine of the quantity specified on entry.
SPEC: %EXTERNALLONGREALFNSPEC HYPSIN(%LONGREAL X)
CALL: HYPSIN(X)
X is a real or longreal expression.
The real or longreal value of the hyperbolic sine
y =
of the quantity specified by X is returned.
ERROR CONDITIONS: If the modulus of x is greater than or equal to 172.694 the
program will terminate with the message:
HYPSIN ARG OUT OF RANGE
HYPTAN
DEFINITION: This real or longreal function gives the value of the hyperbolic
tangent of the quantity specified on entry.
SPEC: %EXTERNALLONGREALFNSPEC HYPTAN(%LONGREAL X)
CALL: HYPTAN(X)
X is a real or longreal expression.
The real or longreal value of the hyperbolic tangent
y =
of the quantity specified by X is returned.
ERROR CONDITIONS: None.
IMOD
DEFINITION: This integer function gives the value of the modulus of the integer
quantity specified on entry.
SPEC: Not required.
CALL: IMOD(N)
N is an integer expression.
ERROR CONDITIONS: Integer overflow occurs if an attempt is made to take the
modulus of the largest negative integer (-2147483648).
INSTREAM
DEFINITION: This integer function returns the number of the stream currently
selected for input.
SPEC: %EXTERNALINTEGERFNSPEC INSTREAM
CALL: INSTREAM
No parameters.
ERROR CONDITIONS: None
INT
DEFINITION: This integer function gives the value of the nearest integer to the
quantity specified on entry.
SPEC: Not required.
CALL: INT(X)
X is a longreal expression.
The value of the nearest integer to x is returned.
ERROR CONDITIONS: In checking mode if (x+ 0.5) is outwith the range of a 32-bit
integer the program terminates with the message:
INT PT TOO LARGE
This error is trappable as event 1/7.
INTEGER
DEFINITION: This map enables the user to access a particular 4-byte location
whose address is specified by the parameter.
SPEC: Not required.
CALL: INTEGER(N)
N is an integer expression giving the absolute address in core of
the required location.
This map may be used to access the contents of a correctly aligned 4-byte
location, as though it held an %INTEGER variable, or to store an integer
value at the specified address:
%INTEGER I
%OWNBYTEINTEGERARRAY A(1:4) = 'A','B','C','D'
I = INTEGER(ADDR(A(1))); !I now contains M'ABCD'
INTEGER(ADDR(A(1))) = 0; !All elements of A now contain
0
ERROR CONDITIONS: If the specified location is not correctly full-word aligned,
an address error occurs when the routine attempts to access it.
INTPT
DEFINITION: This integer function gives the value of the integral part of the
quantity specified on entry.
SPEC: Not required.
CALL: INT PT(X)
X is a real or longreal expression.
The integral part of x is returned.
The integral part is the integer that is less than or equal to the
expression.
Hence INT PT (-3.6) is -4.
ERROR CONDITIONS: In checking mode if (x + 0.5) is outwith the range of a 32-bit
integer the program terminates with the message:
INT PT TOO LARGE
This error is trappable as event 1/7.
INVERT
DEFINITION: This routine inverts an NxN matrix, making use of the routines DIV
MATRIX and UNIT. The method of Gaussian elimination with partial
pivoting is used. The given matrix is destroyed.
SPEC: %EXTERNALROUTINESPEC INVERT (%LONGREALARRAYNAME A,B, %INTEGER N,
%LONGREALNAME DET)
CALL: INVERT (A,B,N,DET)
A,B are the names of two longreal two-dimensional arrays.
Array B contains the matrix to be inverted.
The required inverse is placed in A and the input matrix is
destroyed.
N is the integer expression whose value gives an upper limit for the
dimensions of the given arrays, the lower bounds being taken to be
1.
DET is the name of a longreal variable which is set to the value of
the determinant of the matrix in array B.
Note that large errors may occur if the matrix is ill-conditioned, and if
this is suspected, perturbed matrices should be examined.
ERROR CONDITIONS: If N is less than, or equal to zero, the program terminates
with the message:
INVERT DATA FAULT N = n
ISOCARD
DEFINITION: This routine reads the next card or next card image from the
currently selected input stream, and fills the 80-byte array specified on
entry starting at element 1 of the array.
SPEC: %EXTERNALROUTINESPEC ISO CARD (%BYTEINTEGERARRAYNAME A)
CALL: ISO CARD (A)
A is the name of a byte integer array.
The array A contains the Edinburgh ISO equivalents of the card punching.
Note that valid extended Hollerith characters which have no ISO
equivalent will be interpreted as SUB(X'1A'). Punchings which lie
outside the 256 character extended Hollerith code will result in card
rejection by the hardware.
When reading from an EMAS file records of less than 80 bytes are space
filled; records greater than 80 bytes are truncated and the excess lost.
ERROR CONDITIONS: None.
LENGTH
DEFINITION: This map accesses the location containing the current length of a
string.
SPEC: Not required.
CALL: LENGTH(S)
S is the name (of type %STRING of the location containing the string
whose length byte is to be accessed.
This map enables the number of characters in a string to be measured or
adjusted without knowing the physical layout of the string.
Note if the length of the string is increased the characters 'added' to
the string will be undefined.
ERROR CONDITIONS: None.
LENGTHENI
DEFINITION: This longinteger function extends an operand in an expression from
type %INTEGER to %LONGINTEGERj"4 SPEC:Not required.
CALL: LENGTHEN(I)
I is an integer expression.
ERROR CONDITIONS: None
LENGTHENR
DEFINITION: This longlongreal function extends an operand in an expression from
type %LONGREAL to %LONGLONGREALj"4 SPECNot required.
CALL: LENGTHENR(A)
A is a longreal expression.
ERROR CONDITIONS: None.
LINT
DEFINITION: This longinteger function gives the value of the integer nearest to
the value specified on entry.
SPEC: Not required.
CALL: LINT(A)
A is a longlongreal expression.
ERROR CONDITIONS: Overflow will occur if (A + 0.5) is outside the range of a
longinteger.
LINTPT
DEFINITION: This longinteger function gives the value of the largest integer
less than or equal to the value specified on entry.
SPEC: Not required.
CALL: LINTPT(A)
A is a longlongreal expression.
ERROR CONDITIONS: Overflow will occur if (A + 0.5) is outside the range of a
longinteger.
LOG
DEFINITION: This longreal function gives the value of the logarithm to the base
'e' of the quantity specified on entry.
SPEC: Not required.
CALL: LOG(X)
X is a real or longreal expression.
ERROR CONDITIONS: If x is negative the program terminates with the message:
LOG ARG NEGATIVE
If x is zero the program terminates with the message:
LOG ARG ZERO
LOGGAMMA
DEFINITION: This longreal function gives the value of the log-gamma function of
the quantity specified on entry.
SPEC: %EXTERNALLONGREALFNSPEC LOGGAMMA(%LONGREAL X)
CALL: LOGGAMMA(X)
X is a real or longreal expression.
The real or longreal value of the logarithm to the base 'e' of the gamma
function of the quantity specified by X, i.e. log (x) is returned.
ERROR CONDITIONS: If x is less than or equal to zero, the program terminates
with the message:
LGAMMA ARG NOT POSITIVE
If x is greater than or equal to 4.2913*10 the program terminates with
the message:
LGAMMA ARG TOO LARGE
LOGTEN
DEFINITION: This real or longreal function gives the common logarithm to the
base 10 of the quantity specified on entry.
SPEC: %EXTERNALLONGREALFNSPEC LOGTEN (%LONGREAL X)
CALL: LOGTEN(X)
X is a real or longreal expression.
ERROR CONDITIONS: If x is negative the program terminates with the message:
LOG ARG NEGATIVE
If x is zero the program terminates with the message:
LOG ARG NEGATIVE
LONGINTEGER
DEFINITION: This longinteger map enables the user to access a particular 8-byte
location whose address is specified on entry.
SPEC: Not required.
CALL: LONGINTEGER(I)
I is an integer expression giving the absolute address in core of
the required location.
ERROR CONDITIONS: If the specified address is not double-word aligned or refers
to a protected area of core then the effect is undefined.
LONGLONGREAL
DEFINITION: This longlongreal map enables the user to access a particular
16-byte location whose address is specified by the parameter.
SPEC: Not required.
CALL: LONGLONGREAL(I)
I Is an integer expression giving the address of the location to be
accessed.
ERROR CONDITIONS: If the address is not double-word aligned or refers to a
protected area of core then the effect is undefined.
LONGREAL
DEFINITION: This map enables the user to access a particular long real location
whose address is specified as the parameter.
SPEC: Not required.
CALL: LONG REAL (N)
N is an integer expression giving the address of the location to be
accessed.
This map may be used to access the contents of a correctly aligned
location as though it were a %LONGREAL variable, or to store a longreal
value at the specified address:
%INTEGERARRAY A(1:2)
%LONGREAL R
R = 3.141592653589793; !PI, double precision
LONGREAL(ADDR(A(1))) = R; !array A now contains the 64 bit pattern
in R
A(2) = 0
R = LONGREAL(ADDR(A(1))); !R now contains PI, single precision.
Note that LONG REAL is always double length and is not affected by
%REALSNORMALj"ERROR CONDITIONS: If the specified location is not
correctly double word aligned the effect when the map attempts to access
it is undefined.
LRANDOM
DEFINITION: This longreal function produces a set of random numbers either in a
rectangular or Gaussian distribution.
SPEC: %EXTERNALLONGREALFNSPEC LRANDOM(%INTEGERNAME I, %INTEGER N)
CALL: LRANDOM(I,N)
I is the name of an integer variable which must be initialised to
any odd integer. Note that a value of I < 50001 may produce a
sequence which is similar in the first few terms.
N is an integer expression whose value controls the type of
distribution:
N = 1 gives a rectangular distribution,
n > 1 gives a Gaussian distribution with a mean value of n/2 and a
standard deviation of . For a Gaussian distribution a value of
n greater than 10 is recommended.
A longreal number in the range 0-n is returned. Note that I contains an
integer random sequence in the range 0-(2 -1).
Users may wish to scale the distribution. To produce Z with Gaussian
distribution, mean X, and standard deviation S, call LRANDOM with N = 12
and scale thus:-
Z = (LRANDOM(I,12)-6)*S+X
ERROR CONDITIONS: If N is negative the program terminates with the message:
NEGATIVE ARGUMENT IN RANDOM.
MOD
DEFINITION: This longreal function gives the value of the modulus (i.e. the
absolute value) of the quantity specified on entry.
SPEC: Not required.
CALL: MOD(X)
X is a real or longreal expression.
ERROR CONDITIONS: None.
MULTMATRIX
DEFINITION: This routine forms the matrix product A = BC where B is NxP, C is
PxM, and A, the product is NxM. The arrays used must be distinct.
SPEC: %EXTERNALROUTINESPEC MULT MATRIX(%LONGREALARRAYNAME A,B,C, %INTEGER
N,P,M)
CALL: MULT MATRIX (A,B,C,N,P,M)
A,B,C are the names of three longreal two-dimensional arrays.
Arrays B and C contain the rectangular matrices to be multiplied
together.
Matrix multiplication is performed on the matrices stored in
arrays B and C. The resulting matrix is stored in array A.
Arrays B and C are unchanged.
N,P,M are integer expressions whose values give the upper bounds of the
dimensions for the given arrays, the lower limits being taken to
be 1.
ERROR CONDITIONS: If the upper bounds of any of the arrays are zero or negative,
the program terminates with the message:
MATRIX BOUND ZERO OR NEGATIVE
MULTTRMATRIX
DEFINITION: This routine forms the transpose matrix product A = BC where C is
the transpose of a given MxP matrix C. If matrix B is NxP, then A is
NxM. The arrays used must be distinct.
SPEC: %EXTERNALROUTINESPEC MULT TR MATRIX (%LONGREALARRAYNAMEj! " # %INTEGER
N,P,M)
CALL: MULT TR MATRIX (A,B,C,N,P,M)
A,B,C are the names of three longreal two-dimensional arrays. The array
C contains the matrix to be transposed, and array B contains the
matrix by which the transpose is to be multiplied.
The matrix in array B is multiplied by the transpose of the matrix
in C. The resulting matrix is stored in array A. Arrays B and C
are unchanged.
N,P,M are the integer expressions whose values give the upper limits of
the dimensions of the given arrays, the lower limits being taken
to be 1. Note that C has dimensions M and P in that order.
ERROR CONDITIONS: If any of the upper bounds of the matrices is zero or
negative, the program terminates with the message:
MATRIX BOUND ZERO OR NEGATIVE
NEWLINE
DEFINITION: This routine produces a 'newline' character on the currently
selected output stream.
SPEC: Not required.
CALL: NEWLINE
No parameters.
ERROR CONDITIONS: If an attempt is made to output more data than has been
specified for the current output stream, the program terminates with the
message:
OUTPUT EXCEEDED
NEWLINES
DEFINITION: This routine produces the specified number of 'newline' characters
on the currently selected output stream.
SPEC: Not required.
CALL: NEWLINES(N)
N is an integer expression, the last 8 bits of which indicate the
number of 'newline' characters to be output.
n 'newline' characters are produced on the output stream. Note that n <=
0 has no effect.
ERROR CONDITIONS: If an attempt is made to output more data than has been
specified for the current output stream, the program terminates with the
message:
OUTPUT EXCEEDED
NEWPAGE
DEFINITION: This routine causes the 'form-feed' character to be put into the
output stream.
SPEC: Not required.
CALL: NEWPAGE
No parameters.
The 'form-feed' character is put into the output stream. If the
currently selected output stream goes to the Line Printer, then the paper
is advanced to the head of a new page. The effect on an interactive
terminal depends on the characteristics of the terminal.
ERROR CONDITIONS: If an attempt is made to output more data than has been
specified for the current output stream, the program terminates with the
message:
OUTPUT EXCEEDED
NEXTCH
DEFINITION: This integer function gives the ISO numerical value of the next
character appearing on the currently selected input stream.
SPEC: Not required
CALL: NEXT CH
No parameters.
The ISO numerical value of the next character belonging to the full
Edinburgh Standard Character Set appearing on the input stream is
returned. A subsequent call of READ CH or NEXT CH will obtain the same
character.
ERROR CONDITIONS: If an attempt is made to read more data than has been provided
on the input stream the program terminates with the message:
INPUT ENDED
This error is trappable as event 9/1
NEXTITEM
DEFINITION: This string function reads the next symbol from the currently
selected input stream, as a one-character-string. The symbol may be read
again, for example by NEXT ITEM or NEXT SYMBOL.
SPEC: Not required.
CALL: NEXT ITEM
No parameters.
The ISO-numeric value of the next symbol from the input stream is
obtained. This symbol can be obtained again by either a 'READ ITEM' or a
'NEXT ITEM' instruction.
ERROR CONDITIONS: If an attempt is made to read more data than has been provided
on the input stream, the program terminates with the message:
INPUT ENDED
This error is trappable as event 9/1.
Invalid characters in the input stream are passed through by EMAS, but
under VME/B are replaced by SUB and if SUB is detected by this routine
the program terminates with the message:
SUBSTITUTE CHARACTER IN DATA
This error is trappable as event 3/1.
NEXTSYMBOL
DEFINITION: This integer function gives the ISO numerical value of the next
symbol appearing on the currently selected input stream.
SPEC: Not required.
CALL: NEXT SYMBOL
No parameters.
The ISO numerical value of the next symbol appearing on the input stream
is returned.
A subsequent call of READ SYMBOL or NEXT SYMBOL will obtain the same
symbol.
ERROR CONDITIONS: If an attempt is made to read more data than has been provided
on the input stream, the program terminates with the message:
INPUT ENDED
This error is trappable as event 9/1.
Invalid characters in the input stream are passed through by EMAS, but
under VME/B are replaced by SUB and if SUB is detected by this routine
the program terminates with the message:
SUBSTITUTE CHARACTER IN DATA
This error is trappable as event 3/1.
NL
DEFINITION: This integer function returns as a result the value of the internal
code of the newline character.
SPEC: Not required.
CALL: NL
No parameters.
ERROR CONDITIONS: None.
NULL
DEFINITION: An NxM null matrix is set up by this routine in a specified array.
SPEC: %EXTERNALROUTINESPEC NULL(%LONGREALARRAYNAME A, %INTEGER N,M).
CALL: NULL(A,N,M)
A is the name of a longreal two-dimensional array.
All elements of the array are set to zero.
N,M are the integer expressions whose values, n and m, give upper
bounds for the dimensions of the given array, the lower bounds
being taken to be 1.
ERROR CONDITIONS: If either of the matrix bounds of the array is found to be
zero or negative, the program terminates with the message:
MATRIX BOUND ZERO OR NEGATIVE
OPENDA
DEFINITION: This routine opens the direct access file on logical channel (n).
SPEC: %EXTERNALROUTINESPEC OPENDA (%INTEGER N)
CALL: OPENDA(N)
N is an integer expression which gives the channel number and must
be in the range allowed by the operating system being used.
The file is made ready for reading or writing.
ERROR CONDITIONS: If a file is opened twice without being closed, the program
terminates with the message:
FILE ALREADY OPEN
If an attempt is made to open a file with an invalid channel number or a
channel which has not been defined, the program terminates with an
appropriate error message.
Although the logical channel number must lie in the range appropriate to
the system being used it must not conflict with any channel numbers
assigned to either stream I/O or to sequential files.
The user must declare his direct access file requirements to the
operating system as specified in the appropriate User's Guide.
OPENSQ
DEFINITION: This routine opens a sequential file on the logical channel
indicated.
SPEC: %EXTERNALROUTINESPEC OPENSQ (%INTEGER M)
CALL: OPENSQ(M)
M is an integer expression which specifies the channel number and
must be in the range allowed by the operating system being used.
The file is made ready for reading or writing, but note that both options
may not be exercised.
ERROR CONDITIONS: If a file is opened twice without being closed, the program is
terminated with the message:
FILE ALREADY OPEN
If an attempt is made to open a file with an invalid channel number or a
channel which has not been defined, the program terminates with an
appropriate error message.
Although the logical channel number must lie in the range appropriate to
the system being used it must not conflict with any channel numbers
assigned to either stream I/O or direct access files.
The user must declare his sequential file requirements to the operating
system as specified in the appropriate User's Guide.
OUTPOS
DEFINITION: This integer function returns the position on the current line of
the last character output. Immediately after a call of NEWLINE, OUTPOS
will return the value zero.
SPEC: %EXTERNALINTEGERFNSPEC OUTPOS
CALL: OUTPOS
No parameters.
ERROR CONDITIONS: None
OUTSTREAM
DEFINITION: This integer function returns the number of the stream currently
selected for output.
SPEC: %EXTERNALINTEGERFNSPEC OUTSTREAM
CALL: OUTSTREAM
No parameters.
ERROR CONDITIONS: None
PI
DEFINITION: This longreal function returns the value of (3.141592653589793).
SPEC Not required.
CALL PI
No parameters.
ERROR CONDITIONS: None.
PRINT
DEFINITION: This routine prints the value of the specified real number on the
currently selected output medium in fixed-point form.
SPEC: Not required.
CALL: PRINT(X,M,N)
X is a longreal expression which is to be output.
M is an integer expression indicating how many digits have to be
output before the decimal point.
N is an integer expression indicating how many digits have to be
output after the decimal point.
x is printed via the current output stream in fixed-point form, with m
digits before, and n digits after the decimal point. Insignificant
leading zeros are replaced by spaces and the sign is right justified.
Positive sign is represented by a space.
If more than m significant figures occur before the decimal point, the
point will be displaced to the right and extra digits inserted. The
total number of positions used in printing x is (1+m+1+n).
ERROR CONDITIONS: If an attempt is made to output more data than has been
specified for the current output stream, the program terminates with the
message:
OUTPUT EXCEEDED
PRINTCH
DEFINITION: This routine places the n least significant bits of the parameter as
the next character in the output stream: n is seven under VME/B and eight
on EMAS.
SPEC: Not required.
CALL: PRINT CH (N)
N is an integer expression giving the ISO code representation of the
character to be printed.
The character, represented in ISO code by the last n bits of N, is
printed out on the currently selected output stream.
ERROR CONDITIONS: If an attempt is made to output more data than has been
specified for the current output stream, the program terminates with the
message:
OUTPUT EXCEEDED
PRINTFL
DEFINITION: This routine prints on the output medium the longreal value
specified by the first parameter in floating-point form.
SPEC: Not required.
CALL: PRINT FL (X,N)
X is a longreal expression which is to be printed out.
N is an integer expression indicating the number of digits to be
printed after the decimal point.
A floating-point real number is printed out using n+7 printing positions,
with n digits after the decimal point. The number is standardised in the
range 1 <= x < 10.
ERROR CONDITIONS: If an attempt is made to output more data than has been
specified for the current output stream, the program terminates with the
message:
OUTPUT EXCEEDED
PRINTSTRING
DEFINITION: This routine outputs a string to the currently selected output
stream.
SPEC: Not required.
CALL: PRINT STRING(S)
S is the string expression to be output.
ERROR CONDITIONS: If an attempt is made to output more data than has been
specified for the current output stream, the program terminates with
the message:
OUTPUT EXCEEDED
PRINTSYMBOL
DEFINITION: This routine prints on the currently selected output stream the
symbol whose ISO code value is specified on entry.
SPEC: Not required.
CALL: PRINT SYMBOL(N)
N is an integer expression giving the ISO code representation of the
symbol to be printed.
The symbol, represented in ISO code by the last 7 bits of N, is printed
out on the currently selected output stream. If the symbol is not in the
IMP extended character set, SUB is placed in the output stream.
ERROR CONDITIONS: If an attempt is made to output more data than has been
specified for the current output stream, the program terminates with the
message:
OUTPUT EXCEEDED
RADIUS
DEFINITION: This longreal function gives the value of the radius of a circle
whose equation is of the form X +Y = R (where R is the radius).
SPEC: Not required.
CALL: RADIUS(X,Y)
X,Y are real or longreal expressions.
The real or longreal value of the radius, i.e. the value of the positive
square root of (x +y ), is returned.
ERROR CONDITIONS: If x or x +y is greater than the largest permissible real
number an overflow condition will occur and the program will terminate
with the message:
RADIUS ARGS TOO LARGE
RANDOM
DEFINITION: This real function produces a set of random numbers either in a
rectangular or Gaussian distribution.
SPEC: %EXTERNALREALFNSPEC RANDOM(%INTEGERNAME I, %INTEGER N)
CALL: RANDOM(I,N)
I is the name of an integer variable which must be initialised to
any odd integer. Note that a value of I < 50001 may produce a
sequence which is similar in the first few terms.
N is an integer expression whose value controls the type of
distribution:
N = 1 gives a rectangular distribution,
n > 1 gives a Gaussian distribution with a mean value of n/2 and a
standard deviation of . For a Gaussian distribution a value of
n greater than 10 is recommended.
A real number in the range 0-n is returned. Note that I contains an
integer random sequence in the range 0-(2 -1).
Users may wish to scale the distribution. To produce Z with Gaussian
distribution, mean X, and standard deviation S, call RANDOM with N = 12
and scale thus:-
Z = (RANDOM(I,12)-6)*S+X
ERROR CONDITIONS: If N is negative the program terminates with the message:
NEGATIVE ARGUMENT IN RANDOM.
Wrong results occur if RANDOM instead of LRANDOM is called when
%REALSLONG is in operation.
READ
DEFINITION: This routine reads numerical data from the currently selected input
stream and uses 'READ SYMBOL' (q.v.). The number read may be in fixed or
floating point form.
SPEC: Not required.
CALL: READ (X)
X is the name of an integer or real variable.
The next number is taken from the input stream and stored in X. Numbers
whose modulus is less than 2.4x10 are treated as zero. Numbers whose
modulus is greater than 7.2x10 will overflow.
ERROR CONDITIONS: If any characters other than digits + - @ . occur, the program
terminates with the message:
SYMBOL IN DATA
followed by the invalid symbol. This error is trappable as event 4/1.
In the current implementation, if this error is trapped the offending
symbol may be obtained using READ SYMBOL.
If an attempt is made to read more data than has been provided on the
input stream, the program terminates with the message:
INPUT ENDED
This error is trappable as event 9/1.
READCH
DEFINITION: This routine reads a character from the input stream in internally
coded form before any line reconstruction is done.
SPEC: Not required.
CALL: READ CH (N)
N is the name of an integer variable.
The next character on the input stream, belonging to the full Edinburgh
Standard Character Set, is read in and stored in the location specified
by N. The character is stored (in internal code) in the 8 least
significant bits of N.
ERROR CONDITIONS: If an attempt is made to read more data than has been provided
on the input stream, the program terminates with the message:
INPUT ENDED
This error is trappable as event 9/1.
READDA
DEFINITION: This routine reads data from a direct access file, connected as the
channel specified, into the specified area, starting from the specified
record on the file.
SPEC: %EXTERNALROUTINESPEC READDA (%INTEGER N, %INTEGERNAMEj3%#4 %NAME BEGIN,
END)
CALL: READDA (N,SECT,BEGIN,END)
N is an integer expression which specifies the channel number.
SECT is an %INTEGERNAME parameter whose value on entry specifies the
record at which reading is to start, and on exit contains the
number of the last record read from.
BEGIN are variable names or array elements which specify the area into
which data is
END to be read.
Information is read from the direct access file on channel n starting at
record sect and is written into the area starting at BEGIN and finishing
at the end of END. This area is normally an array.
ERROR CONDITIONS: If ADDR(END) < ADDR(BEGIN), the program terminates with the
message:
ADDRESSES INSIDE OUT.
If an attempt is made to access a record on the file which does not
exist, the program terminates with the message:
RECORD NUMBER OUT OF RANGE
If the specified channel is not open, the program terminates with:
FILE NOT OPEN
If an invalid record size has been specified in a file definition, the
program terminates with the message:
INVALID RECORD SIZE
If an input or output request is not consistent with the file definition,
the program terminates with the message:
INVALID OPERATION ON FILE
If an attempt is made to read from a file with an invalid channel number
or one which has not been defined, the program terminates with an
appropriate error message.
The record size for direct access files is fixed at 1024 bytes and, on
creation, the complete file is filled with the unassigned pattern.
READITEM
DEFINITION: This routine reads the next symbol from the currently selected input
stream, and sets this up as a one-character string.
SPEC: Not required.
CALL: READ ITEM (S)
S is the name (of type %STRING of the location in which the symbol
is stored.
The ISO-numeric value of the next symbol from the input stream is stored
in S.
ERROR CONDITIONS: If an attempt is made to read more data than has been provided
on the input stream, the program terminates with the message:
INPUT ENDED
This error is trappable as event 9/1.
Invalid characters in the input stream under VME/B only are replaced by
SUB.
READLSQ
DEFINITION: This routine reads information from a sequential file, connected as
the channel specified on entry, into the array specified on entry.
SPEC: %EXTERNALROUTINESPEC READLSQ(%INTEGER N, %NAME BEGIN,END, %INTEGERNAME L)
CALL: READLSQ(N,BEGIN,END,L)
N is an integer expression specifying the channel number and whose
value must be in the range allowed by the operating system being
used.
BEGIN are variable or array element names which specify the area into
which the
END information is to be read.
L is the name of an integer which will return the length in bytes of
the record just read. If an attempt is made to read more data
than has been provided on the input stream L will be set to the
value zero.
ERROR CONDITIONS: If the specified channel is not open the program will
terminate with the message:
FILE NOT OPEN
If ADDR(END) < ADDR(BEGIN), the program will terminate with the message:
ADDRESSES INSIDE OUT
If an attempt is made to read from a file with an invalid channel number
or one which has not been defined, the program terminates with an
appropriate error message.
READSQ
DEFINITION: This routine reads information from a sequential file, connected as
the channel specified on entry, into the array specified on entry.
SPEC: %EXTERNALROUTINESPEC READSQ (%INTEGER M, %NAME BEGIN,END)
CALL: READSQ(M,BEGIN,END)
M is an integer expression which specifies the channel number and
whose value must be in the range allowed by the operating system
being used.
BEGIN are variable names or array elements which specify the area into
which the
END information is to be read.
Information is read from the channel specified on entry into the area
starting at location BEGIN, and finishing at the end of location END.
The area specified is normally an array.
ERROR CONDITIONS: If the specified channel is not open the program will
terminate with the message:
FILE NOT OPEN
If ADDR(END) < ADDR(BEGIN), the program will terminate with the message:
ADDRESSES INSIDE OUT
If an attempt is made to read beyond the end of a file, the program
terminates with the message:
INPUT ENDED
This error is trappable as event 9/1.
If an attempt is made to read from a file with an invalid channel number
or one which has not been defined, the program terminates with an
appropriate error message.
READSTRING
DEFINITION: This routine reads the next string from the currently selected input
stream.
SPEC: Not required.
CALL: READ STRING (S)
S is the name (of type %STRING of the location in which the string
of symbols is stored.
The string of symbols (which must be enclosed within double quotes and
must contain 255 or less symbols) is read into S.
ERROR CONDITIONS: If the first significant symbol read by READ STRING (ignoring
spaces and newlines) is not a double quote, the program terminates with
the message:
SYMBOL INSTEAD OF STRING
If the declared maximum length of the stringname parameter is
insufficient to hold the string, the program terminates with the message:
CAPACITY EXCEEDED
If an attempt is made to read more data than has been provided on the
input stream, the program terminates with the message:
INPUT ENDED
This error is trappable as event 9/1.
Invalid characters in the input stream are passed through by EMAS, but
under VME/B are replaced by SUB and if SUB is detected by this routine
the program terminates with the message:
SUBSTITUTE CHARACTER IN DATA
This error is trappable as event 3/1.
READSYMBOL
DEFINITION: This routine reads the next symbol which appears on the currently
selected input stream.
SPEC: Not required.
CALL: READ SYMBOL(N)
N is the name of an integer or byteinteger variable.
The next symbol on the input stream is read in and stored in the location
specified by N.
The symbol is stored (in internal code) in the 7 least significant bits
of N.
All non-printing characters, (including CR), are ignored.
ERROR CONDITIONS: If an attempt is made to read more data than has been provided
on the input stream, the program terminates with the message:
INPUT ENDED
This error is trappable as event 9/1.
Invalid characters in the input stream are passed through by EMAS, but
under VME/B are replaced by SUB and if SUB is detected by this routine
the program terminates with the message:
SUBSTITUTE CHARACTER IN DATA
This error is trappable as event 3/1.
REAL
DEFINITION: This map enables the user to access a particular 4-byte location
whose address is specified by the parameter.
SPEC: Not required.
CALL: REAL(N)
N is an integer expression giving the address of the location to be
accessed.
This may be used to access a correctly aligned 4-byte location, as though
it held a %REAL variable, or to store a real value at the specified
address:
%INTEGER L
%REAL R
R = 54.3
REAL(ADDR(L)) = R; !L now contains 54.3 held as a floating
!point number
PRINT(L,6,1); !The bit pattern in L is treated as that
!of an integer value. 54.3 will not be
!the value printed.
PRINT(REAL(ADDR(L)),6,1); !54.3 is printed.
Note that REAL is always single length and is not affected by
%REALSLONGj"ERROR CONDITIONS: If the specified location is not correctly
full-word aligned, address truncation occurs when the routine attempts to
access it.
RECORD
DEFINITION: This mapping function renders the absolute address specified on
entry in a form such that it may be assigned to a %RECORDNAME variable
using the '==' assignment operator.
SPEC: Not required.
CALL: RECORD(ADR)
ADR is an integer expression giving the absolute address of the core
area to be treated as a record.
The address, in a form such that it can be assigned to a %RECORDNAME
variable using the '==' assignment operator, is returned.
The following example illustrates the use of a record map:
%INTEGERARRAY NAME(1:11)
%RECORDFORMAT R1(%INTEGER I,J, %BYTEINTEGER K,L,M,N, %STRING (15)
S,T)
%RECORDNAME R(R1)
R == RECORD (ADDR(NAME(1)))
R
_I is a reference to NAME(1)
R
_K is a reference to the top byte of NAME(3)
For more information on records see the Edinburgh IMP Language Manual.
ERROR CONDITIONS: If the address specified is not double word aligned the
effects are undefined.
SELECTINPUT
DEFINITION: This routine causes subsequent input to be taken from the stream
specified on entry.
SPEC: Not required.
CALL: SELECT INPUT(N)
N is an integer expression giving the number of the input stream to
be selected, and whose value must lie in the range allowed by the
operating system being used.
The current input is connected to the stream specified by N. All further
input is obtained via the new stream.
Under VME/B any unused information from the current record is lost during
execution of this routine.
ERROR CONDITIONS: If no stream is defined on entry to this routine the program
terminates with the message:
STREAM NOT DEFINED
If the stream defined has previously been defined for output, the program
terminates with the message:
STREAM IN USE
SELECTOUTPUT
DEFINITION: This routine causes subsequent output to be sent to the stream
specified on entry.
SPEC: Not required.
CALL: SELECT OUTPUT(N)
N is an integer expression giving the number of the output stream
selected and must be in the range allowed by the operating system
being used.
Under VME/B the current record is output to the previously selected
stream unless the last symbol output before the call of this routine was
a 'newline' symbol. In the latter case, nothing is output. All
subsequent records are sent to the new stream.
ERROR CONDITIONS: If no stream is defined on entry to this routine the program
terminates with the message:
STREAM NOT DEFINED
If the stream defined has been previously defined for input, the program
terminates with the message:
STREAM IN USE
If an attempt is made to output more data than has been specified for the
current output stream, the program terminates with the message:
OUTPUT EXCEEDED
SETMARGINS
DEFINITION: This routine allows the margins of either the current input or the
current output user-defined stream (i.e. any stream lying between 1 and
98 inclusive) to be changed. This routine is only available under VME/B.
SPEC: Not required.
CALL: SET MARGINS (M,LEFT,RIGHT)
M is an integer expression which gives the number of the stream
whose margins are to be changed.
LEFT is an integer expression specifying the left hand margin and can
take values 1 <= left <= right.
RIGHT is an integer expression specifying the right hand margin and can
take values left <= right <= 160 for input streams or left <=
right <= 132 for output streams.
If SET MARGINS operates on the current input stream, the default values
for which are left = 1, right = 80, (with an exception for Stream 99:
right = 132), left and right may take values which satisfy 1 <= left <=
right <= 160. The effect of changing input margins is truncation of the
input record at the beginning if left is increased or truncation of the
input record at the end if right is reduced. If SET MARGINS operates on
the current output stream, the default values for which are left = 1,
right = 120, left and right may take values which satisfy 1 <= left <=
right <= 132. The effect of altering the left hand margin is to inset
the output record, and the effect of reducing the right hand margin is to
output any overflow on the next line. The margins, once set on a given
stream, remain as characteristics of that stream until the next call of
SET MARGINS for the stream.
ERROR CONDITIONS: If m is not the current input or output stream; if m < 1 or m
> 98; the program terminates with the message:
STREAM NOT DEFINED
If left > right or if either lies outside their defined limits, the
program terminates with the message:
INVALID MARGINS
SHIFTC
DEFINITION: This integer function cyclically shifts a given bit pattern by a
specified number of bits.
SPEC: %EXTERNALINTEGERFNSPEC SHIFTC (%INTEGER N,M)
CALL: SHIFTC (N,M)
N is an integer expression whose binary pattern is to be shifted.
M is an integer expression indicating the number of places n is to
be shifted. Note that m may be positive, indicating a shift to
the left, or negative, indicating a shift to the right.
The bit pattern of the integer in location N is shifted m places, left or
right according to the sign (+ or - respectively) of m.
Bits lost off one end of the word reappear in the same order at the other
end of the word.
ERROR CONDITIONS: If the absolute value of m is greater than 32, the program
terminates with the message:
ILLEGAL SHIFT
SHORTENI
DEFINITION: This integer function changes an operand in an expression from type
%LONGINTEGER to %INTEGERj"4 SPEC:Not required.
CALL: SHORTENI(L)
L is a longinteger expression.
ERROR CONDITIONS: In checking mode overflow will occur if L is too large to be
contained in an integer.
SHORTENR
DEFINITION: This longreal function changes an operand in an expression from type
%LONGLONGREAL to %LONGREALj"4 SPEC:Not required.
CALL: SHORTEN(R)
R is a longlongreal expression.
ERROR CONDITIONS: None.
SIN
DEFINITION: This longreal function gives the value of the sine of the quantity
specified on entry. This quantity must be in radians.
SPEC: Not required.
CALL: SIN(X)
X is a real or longreal expression.
ERROR CONDITIONS: If the modulus of the argument of this function is greater
than 3.53 x 10 , the result would be wholly inaccurate and the program
terminates with the following message:
SIN ARG OUT OF RANGE
SKIPSYMBOL
DEFINITION: This routine passes over the next symbol which appears on the
currently selected input stream, without reading it.
SPEC: Not required.
CALL: SKIP SYMBOL
No parameters.
ERROR CONDITIONS: If an attempt is made to read more data than has been provided
on the input stream, the program terminates with the message:
INPUT ENDED
This error is trappable as event 9/1.
Invalid characters in the input stream under VME/B only are replaced by
SUB.
SOLVELNEQ
DEFINITION: This routine solves a linear system of equations Ax = b for vector
x. A, an NxN matrix, and b, a vector, are destroyed. The method of
Gaussian elimination with partial pivoting is used.
SPEC: %EXTERNALROUTINESPEC SOLVE LN EQ (%LONGREALARRAYNAME A,B, %INTEGER N,
%LONGREALNAME DET)
CALL: SOLVE LN EQ (A,B,N,DET)
A is the name of a longreal two-dimensional array which contains
square matrix A on input.
B is the name of a longreal one-dimensional array which contains
vector b on input.
N is the integer expression whose value, n, gives an upper limit for
the dimensions of A and B, the lower limits being taken to be 1.
DET is the name of a longreal variable which is set by the routine to
the value of the determinant of the matrix in array A.
The solution of the equations, x, is placed in B, and matrix a is
destroyed.
The value of the determinant of a is placed in DET.
Note that large errors may occur if the matrix is ill-conditioned and, if
this is suspected, perturbed matrices should be examined.
ERROR CONDITIONS: If n is less than or equal to zero, the program terminates
with the message:
SOLVE LN EQ DATA FAULT N = n
If the matrix is not invertible, the value of DET will be zero on exit.
SPACE
DEFINITION: This routine produces one 'space' character on the currently
selected output stream.
SPEC: Not required.
CALL: SPACE
No parameters.
ERROR CONDITIONS: If an attempt is made to output more data than has been
specified for the current output stream, the program terminates with the
message:
OUTPUT EXCEEDED
SPACES
DEFINITION: This routine produces the specified number of 'space' characters on
the currently selected output stream.
SPEC: Not required.
CALL: SPACES(N)
N is an integer expression the last 8 bits of which indicate the
number of 'space' characters to be produced.
n 'space' characters are produced on the output stream.
ERROR CONDITIONS: If an attempt is made to output more data than has been
specified for the current output stream, the program terminates with the
message:
OUTPUT EXCEEDED
SQRT
DEFINITION: This longreal function gives the value of the positive square root
of the quantity specified on entry.
SPEC: Not required.
CALL: SQRT(X)
X is a real or longreal expression.
The real or longreal value of the positive square root of the quantity
specified by X is returned.
ERROR CONDITIONS: If a negative argument is passed to this routine, the program
terminates with the message:
SQRT ARG NEGATIVE
STRING
DEFINITION: This map enables the user to access, as a %STRING a location whose
address is specified by the parameter.
SPEC: Not required.
CALL: STRING(N)
N is an integer expression giving the absolute address in core of
the required location.
This map may be used to access the contents of a location as though it
held a %STRING variable, or to store a string at the specified address:
Note that the first byte of a string is taken as the length of the
string.
%STRING S
%BYTEINTEGERARRAY A(0:10)
S = "ABCDEFGHIJ"
STRING(ADDR(A(0))) = S; !now A(0) = 10,A(1) = 'A'
!A(2) = 'B'--- A(10) = 'J'
A(O) = 4
S = STRING(ADDR(A(O))); !now S = "ABCD"
ERROR CONDITIONS: None.
SUBMATRIX
DEFINITION: This routine subtracts one NxM matrix from another.
SPEC: %EXTERNALROUTINESPEC SUB MATRIX (%LONGREALARRAYNAME A,B,C, %INTEGER N,M)
CALL: SUB MATRIX(A,B,C,N,M)
A,B,C are the names of three longreal two-dimensional arrays. The
matrix in array C is subtracted from the matrix in B.
Array A contains the matrix difference of matrices in arrays B and
C.
Arrays B and C are unchanged.
N,M are the integer expressions whose values give the upper limits for
the dimensions of A, B and C, the lower limits being taken to be
1.
ERROR CONDITIONS: If the array bounds of any of the matrices are zero or
negative, the program terminates with the message:
MATRIX BOUND ZERO OR NEGATIVE
TAN
DEFINITION: This longreal function gives the value of the tangent of the
quantity specified on entry. This quantity must be in radians.
SPEC: Not required.
CALL: TAN(X)
X is a real or longreal expression.
The real or longreal value of the tangent of x is returned.
ERROR CONDITIONS: If the modulus of the argument of this function is greater
than 3.53 x 10 the result would be wholly inaccurate, and the program
terminates with the message:
TAN ARG OUT OF RANGE
TIME
DEFINITION: This string function yields the current time of day.
SPEC: %EXTERNALSTRINGFNSPEC TIME
CALL: TIME
No parameters.
The time is returned in the form hh:mm:ss, and may be printed out using
PRINTSTRING.
ERROR CONDITIONS: None.
TOSTRING
DEFINITION: This string function creates a one-character string.
SPEC: Not required.
CALL: TO STRING(N)
N the least significant 7 bits of the integer expression N represent
the ISO code value of the character to be placed in the string.
A one-character string, containing the character specified by N, is
created.
ERROR CONDITIONS: None.
TRANSMATRIX
DEFINITION: This routine sets up, in a specified two-dimensional array, the NxM
transpose of a given MxN matrix. The specified arrays must be distinct.
SPEC: %EXTERNALROUTINESPEC TRANS MATRIX (%LONGREALARRAYNAME A,B, %INTEGER N,M)
CALL: TRANS MATRIX (A,B,N,M)
A,B are the names of two longreal two-dimensional arrays.
Array B contains the rectangular matrix to be transposed.
The transpose of the matrix stored in array B is set up in the
array A.
Array b is unchanged.
N,M are the integer expressions whose values, n and m, give upper
bounds for the dimensions of the specified arrays, the lower
bounds being taken to be 1.
ERROR CONDITIONS: If the upper bounds of either matrix are zero or negative, the
program terminates with the message:
MATRIX BOUND ZERO OR NEGATIVE
UNIT
DEFINITION: An NxN unit matrix is set up in a specified array.
SPEC: %EXTERNALROUTINESPEC UNIT (%LONGREALARRAYNAME A, %INTEGERj.j"CALL:UNIT
(A,N)
A is the name of a two-dimensional longreal array.
The diagonal elements of A are set to 1 and all other elements to
zero.
N is the integer expression whose value, n, gives an upper bound for
the dimensions of A, the lower bounds being taken to be 1.
ERROR CONDITIONS: If n is zero or negative, the program terminates with the
message:
MATRIX BOUND ZERO OR NEGATIVE
WRITE
DEFINITION: This routine prints on the output medium the integer value specified
by the first parameter using one character position for the sign and the
next n positions for the digits (where n represents a number specified on
entry to the routine).
SPEC: Not required.
CALL: WRITE(X,N)
X is an integer expression whose value, x, is to be printed out.
N is an integer expression specifying the number of digits to be
printed.
An integer is printed out with n significant figures preceded by a sign.
Non-significant leading zeros are suppressed, being replaced by spaces,
and a positive sign is indicated by a space.
If x has more than n significant figures, or if n is zero or negative,
all the figures are printed out, but the righthand end of the number is
then out of alignment. The sign always immediately precedes the most
significant digit.
x is accurate to 11 significant figures.
ERROR CONDITIONS: If an attempt is made to output more data than has been
specified for the current output stream, the program terminates with the
message:
OUTPUT EXCEEDED
WRITEDA
DEFINITION: This routine writes the information held in the specified area onto
the specified file, starting at the specified record.
SPEC: %EXTERNALROUTINESPEC WRITEDA (%INTEGER N, %INTEGERNAMEj3%#4 %NAME BEGIN,
END)
CALL: WRITEDA(N,SECT,BEGIN,END)
N is an integer expression which specifies the channel number and
must be in the range allowed by the operating system being used.
SECT is an %INTEGERNAME parameter whose value on entry specifies the
record at which writing is to start and, on exit, contains the
number of the last record written.
BEGIN are variable names or array elements which specify the area from
which data is to
END be written.
The information contained in core, from BEGIN to END inclusive, is
written to the direct access file on channel n starting at record sect.
Writing always commences at the start of a record and if the information
written does not fill a complete number of records then the remainder of
the last record written is undefined.
ERROR CONDITIONS: If ADDR(END) < ADDR(BEGIN), the program terminates with the
message:
ADDRESSES INSIDE OUT
If an attempt is made to access a non-existent record on the specified
file, the program terminates with the message:
RECORD NUMBER OUT OF RANGE
If the specified channel is not open, the program terminates with:
FILE NOT OPEN
If an attempt is made to write to a file with an invalid channel number
or one which has not been defined, the program terminates with an
appropriate error message.
If an invalid record size has been specified in a file definition, the
program terminates with the message:
INVALID RECORD SIZE
If an input or output request is not consistent with the file definition,
the program terminates with the message:
INVALID OPERATION ON FILE
WRITESQ
DEFINITION: This routine writes the information held in the area specified on
entry onto the next logical record of the sequential file on the channel
specified on entry.
SPEC: %EXTERNALROUTINESPEC WRITESQ (%INTEGER M, %NAME BEGIN,END)
CALL: WRITESQ(M,BEGIN,END)
M is an integer expression which specifies the channel number and
must be in the range allowed by the operating system being used.
BEGIN are variable names or array elements which specify the area from
which the
END information is to be taken.
The information contained in core, between BEGIN and END inclusive, is
written in a new logical record on to the file specified by channel M.
The area specified is normally an array.
ERROR CONDITIONS: If the specified channel is not open the program terminates
with the message:
FILE NOT OPEN
If ADDR(END) < ADDR(BEGIN), the program terminates with the message:
ADDRESSES INSIDE OUT