C      ALGORITHM 663, COLLECTED ALGORITHMS FROM ACM.
C      THIS WORK PUBLISHED IN TRANSACTIONS ON MATHEMATICAL SOFTWARE,
C      VOL. 14, NO. 2, P.177.
      SUBROUTINE BLASDOC
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C            Documentation of vectorized BLAS for the Cyber 205        C
C                                                                      C
C -------------------------------------------------------------------- C
C Language : FORTRAN 200                                               C
C ========                                                             C
C -------------------------------------------------------------------- C
C                                                                      C
C Purpose :                                                            C
C =======                                                              C
C The BLAS, or, Basic Linear Algebra Subprograms, is a set of          C
C subprograms, performing operations on vectors. The BLAS[1]           C
C describes a package of 38 Fortran-callable subprograms. This         C
C package contains only the REAL and COMPLEX subprograms performing    C
C operations on vectors. This means that no DOUBLE PRECISION and no    C
C Givens transformation subprograms have been implemented (see under   C
C "Double Precision" and "Givens transformation").                     C
C According to the LINPACK[2], the subprogram CSROT has been added.    C
C                                                                      C
C For more information on this vectorized BLAS, see [3] and [4].       C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C References :                                                         C
C ==========                                                           C
C 1. C.L. Lawson, R.J. Hanson, D.R. Kincaid, and F.T. Krogh (1979).    C
C    Basic Linear Algebra Subprograms for Fortran Usage, ACM Trans-    C
C    actions on Mathematical Software, 5, 308-323.                     C
C 2. J.J. Dongarra, J.R. Bunch, C.B. Moler, and G.W. Stewart (1979).   C
C    LINPACK user's guide, SIAM publications.                          C
C 3. M. Louter-Nool (1987). Basic Linear Algebra Subprograms (BLAS) on C
C    the CDC Cyber 205, Parallel Computing, 4, 143-165.                C
C 4. M. Louter-Nool. Translation of Algorithm 539: Basic Linear        C
C    Algebra Subprograms for Fortran Usage in FORTRAN 200 for the      C
C    Cyber 205, Report NM-R8702, CWI, Amsterdam, 1987. (Submitted      C
C    to ACM TOMS)                                                      C
C 5. CDC Cyber 200 FORTRAN reference manual, version 1,                C
C    publ. number 60480200.                                            C
C 6. CDC Cyber 200 ASSEMBLER reference manual, version 2,              C
C    publ. number 60485010.                                            C
C 7. CDC VSOS reference manual, version 2,                             C
C    publ. number 6049410.                                             C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C The increment parameters :                                           C
C ========================                                             C
C The parameters INCX and INCY allow the BLAS to operate on vectors    C
C whose elements are non-contiguous in memory. Both positive and       C
C negative values are permitted. Only positive values of INCX are      C
C allowed for operations that have a single vector argument.           C
C If INCX > 0, then the components x(i), i = 1,...,N, of a vector x    C
C are stored in                                                        C
C                                                                      C
C     X(1 + (i - 1) * INCX).                                           C
C                                                                      C
C If INCX < 0, then x(i) is stored in                                  C
C                                                                      C
C     X(1 - (N - i) * INCX).                                           C
C                                                                      C
C The original BLAS permits an INCX value of 0. Here, this option was  C
C not implemented. An error message will be printed.                   C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C Parameters :                                                         C
C ==========                                                           C
C The parameters of BLAS have the following type :                     C
C                                                                      C
C     INTEGER   N, INCX, INCY                                          C
C     REAL      SX(NX), SY(NY), SA, SC, SS                             C
C     COMPLEX   CX(NX), CY(NY), CA                                     C
C                                                                      C
C The dimensions NX of SX (CX), and NY of SY (CY) must satisfy         C
C                                                                      C
C      NX >= 1 + IABS (INCX) * (N - 1).                                C
C      NY >= 1 + IABS (INCY) * (N - 1).                                C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C Type declarations for function names :                               C
C ====================================                                 C
C The function names are of the following type :                       C
C                                                                      C
C     INTEGER   ISAMAX, ICAMAX                                         C
C     REAL      SASUM, SCASUM, SNRM2, SCNRM2, SDOT                     C
C     COMPLEX   CDOTC, CDOTU                                           C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C The subprograms :                                                    C
C ===============                                                      C
C This package contains the following subprograms :                    C
C                                                                      C
C 1.  IMAX = ISAMAX (N, SX, INCX)                                      C
C 2.  IMAX = ICAMAX (N, CX, INCX)                                      C
C     finding the largest component of a vector                        C
C                                                                      C
C 3.  SW = SNRM2  (N, SX, INCX)                                        C
C 4.  SW = SCNRM2 (N, CX, INCX)                                        C
C     computing the Euclidian length or L2 norm of a vector            C
C                                                                      C
C 5.  SW = SASUM  (N, SX, INCX)                                        C
C 6.  SW = SCASUM (N, CX, INCX)                                        C
C     computing the sum of magnitudes of vector components             C
C                                                                      C
C 7.  SW = SDOT  (N, SX, INCX, SY, INCY)                               C
C 8.  SW = CDOTU (N, SX, INCX, SY, INCY)                               C
C 9.  SW = CDOTC (N, SX, INCX, SY, INCY)                               C
C     computing the dot products                                       C
C                                                                      C
C 10. CALL SAXPY (N, SA, SX, INCX, SY, INCY)                           C
C 11. CALL CAXPY (N, CA, CX, INCX, CY, INCY)                           C
C     performing the elementary vector operation: y := a.x + y         C
C                                                                      C
C 12. CALL SSCAL  (N, SA, SX, INCX)                                    C
C 13. CALL CSCAL  (N, CA, CX, INCX)                                    C
C 14. CALL CSSCAL (N, SA, CX, INCX)                                    C
C     performing the vector scaling: x := a.x                          C
C                                                                      C
C 15. CALL SCOPY (N, SX, INCX, SY, INCY)                               C
C 16. CALL CCOPY (N, CX, INCX, CY, INCY)                               C
C     copying a vector x to a vector y:  y := x                        C
C                                                                      C
C 17. CALL SSWAP (N, SX, INCX, SY, INCY)                               C
C 18. CALL CSWAP (N, CX, INCX, CY, INCY)                               C
C     interchanging the vectors x and y: x :=: y                       C
C                                                                      C
C 19. CALL SROT  (N, SX, INCX, SY, INCY, SC, SS)                       C
C 20. CALL CSROT (N, CX, INCX, CY, INCY, SC, SS)                       C
C     applying a plane rotation                                        C
C                                                                      C
C Note :                                                               C
C ----                                                                 C
C For both SROT and CSROT two implementations are available, namely,   C
C SROT - the original SROT3 from [3, 4] - and SROT4, and CSROT         C
C - the original CSROT3 from [3, 4] - and CSROT4, respectively.        C
C The _ROT implementations perform the operations in 3 vector          C
C operations, and the _ROT4 in 4 vector operations. By omitting the    C
C suffix 4 the _ROT4 routines can be loaded instead of the _ROT3's.    C
C The numerical results may differ slightly. For more information      C
C see [3].
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C General comments :                                                   C
C ================                                                     C
C For the REAL vectors the value N should not exceed the number of     C
C data elements on a LARGE PAGE (65535). For COMPLEX vectors the       C
C length is restricted to 32767. If larger values of N are given,      C
C an error message will be printed.                                    C
C                                                                      C
C When operating on non-contiguously stored vectors, a great part      C
C of the execution time will be spent on data movements. So, if        C
C a non-contiguous vector is frequently used, it is wise to copy such  C
C a vector to a contiguously stored vector, e.g., by means of a        C
C BLAS _COPY routine.                                                  C
C                                                                      C
C When both vectors would have a negative increment value, all         C
C subprograms act as if both were positive. This implies that          C
C the process is NOT carried out in reverse storage order. This saves  C
C a lot of probably superfluous reverse operations. If one really      C
C wants to operate in reverse order, we recommend the use of a         C
C _COPY operation, like                                                C
C                                                                      C
C     ASSIGN SXD, .DYN.N                                               C
C     ASSIGN SYD, .DYN.N                                               C
C     CALL SCOPY (N, SX, INCX, SXD, 1)                                 C
C     CALL SCOPY (N, SY, INCY, SYD, 1)                                 C
C     ......                                                           C
C     CALL       (N, SXD, 1, SYD, 1)                                   C
C     ......                                                           C
C     CALL SCOPY (N, SXD, INCX, SX, 1)                                 C
C     CALL SCOPY (N, SYD, INCY, SY, 1)                                 C
C                                                                      C
C                                                                      C
C Note: For one positive and one negative increment value the order    C
C       of processing depends on the increment values and the          C
C       operation involved. In all subprograms the data movements      C
C       were kept to a minimum. For more information see [4].          C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C Implementation :                                                     C
C ==============                                                       C
C The subprograms are coded in CONTROL DATA FORTRAN 200, suitable for  C
C Cyber 200 vector machines. This language is a superset of the ANSI   C
C FORTRAN 77. In order to obtain an optimal code vector intrinsic      C
C functions and SPECIAL CALLS are used. A special call statement       C
C directly generates machine language instructions.                    C
C                                                                      C
C Vector intrinsic functions used (see [5]) :                          C
C -----------------------------------------                            C
C     i = Q8SMAXI  (v)           find the largest element of vector v  C
C     u = Q8VGATHP (v,i,n;u)     gather n elements of v with period i  C
C                                into vector u                         C
C     u = Q8VMERG  (v1,v2,cv;u)  merge the vectors v1 and v2 into u    C
C                                under control of bit vector cv        C
C     u = Q8VREV   (v;u)         store v in reverse order into u       C
C     u = Q8VSCATP (v,i,n;u)     inverse operation of Q8VGATHP         C
C                                                                      C
C Special calls used (see [6]) :                                       C
C ----------------------------                                         C
C     CALL Q8ADDL  (Rf,Sf,Tf)        add lower, full word              C
C     CALL Q8ADDN  (Rf,Sf,Tf)        add normalized, full word         C
C     CALL Q8ADDNS (G,X,A,Y,B,Z,C)   add normalized, sparse vector     C
C     CALL Q8ADDNV (G,X,A,Y,B,Z,C)   add normalized, vector            C
C     CALL Q8ADDX  (Rf,Sf,Tf)        add index, full word              C
C     CALL Q8DOTV  (G,X,A,Y,B,Z,C)   dot product vector                C
C     CALL Q8MAX   (G,X,A, ,B,Z,C)   vector maximum                    C
C     CALL Q8PACK  (Rf,Sf,Tf)        pack, full word                   C
C     CALL Q8SUM   (G,X,A, , ,Z,C)   vector sum                        C
C     CALL Q8VREV  (G,X,A, , ,Z,C)   transmit vector reversed to       C
C                                    vector                            C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C Error messages :                                                     C
C ==============                                                       C
C Error messages will be printed in the following cases :              C
C    1. a) for REAL    vectors when N > 65535                          C
C       b) for COMPLEX vectors when N > 32767                          C
C    2. a) for vectors with one vector argument  when INCX < 1         C
C       b) for vectors with two vector arguments when INCX = 0         C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C Storage :                                                            C
C =======                                                              C
C In each subprogram some BIT vector of length 65535 are declared      C
C and initialized by means of a DATA statement.                        C
C All other auxiliary vectors storage is dynamically allocated.        C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C Execution time :                                                     C
C ==============                                                       C
C In [4] a complete summary of the expected execution times for all    C
C BLAS subprograms as a function of N is given. In general, the        C
C execution time depends on p, the number of pipes of your Cyber 205.  C
C In case of more pipes the execution time is accordingly reduced.     C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C Double precision :                                                   C
C ================                                                     C
C The double precision subprograms have not been vectorized. The       C
C Cyber 205 employs 64-bits full words and 32-bits half words.         C
C The execution time can be increased by a factor of 20 when           C
C operating in double precision instead of single precision. If you    C
C do need double precision results, then use the scalar CDC version    C
C of the BLAS, which is also available via TOMS.                       C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C Givens transformation subprograms :                                  C
C =================================                                    C
C All these subprograms don't use vectors. The codes can be obtained   C
C via TOMS.                                                            C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
C How to use the vectorized BLAS :                                     C
C ==============================                                       C
C The subprograms can be translated with the FORTRAN 200 compiler,     C
C e.g., as follows :                                                   C
C                                                                      C
C      FTN200,OPT,SC,UNS,LO.                                           C
C                                                                      C
C This means :                                                         C
C      The object code is written to the file BINARY/16.               C
C      OPT causes that all optimizations are performed.                C
C      SC interprets names as machine instruction references.          C
C      UNS allows unsafe optimization.                                 C
C      LO delivers the source code and the cross-reference list.       C
C                                                                      C
C For more information about the FTN200 control statement, see [5].    C
C                                                                      C
C Now the binary code can be added to a library at the Cyber 205.      C
C The next control statements are sufficient to create a library       C
C with the BLAS subprograms named OLDLIB.                              C
C                                                                      C
C     OLE,I=BINARY,N=OLDLIB.                                           C
C     DEFINE,OLDLIB.                                                   C
C                                                                      C
C If you want to add the binary code to your existing library, e.g.,   C
C called OLDLIB, then you can use :                                    C
C                                                                      C
C     ATTACH,OLDLIB.                                                   C
C     OLE,I=BINARY,OLDLIB,N=NEWLIB.                                    C
C     DEFINE,NEWLIB.                                                   C
C     PURGE,OLDLIB.                                                    C
C     RETURN,OLDLIB.                                                   C
C     SWITCH,NEWLIB,OLDLIB.                                            C
C                                                                      C
C Your library OLDLIB is replaced by a new library with the same name, C
C including the BLAS subprograms with the same name.                   C
C                                                                      C
C Since FORTRAN 200 is a superset of ANSI FORTRAN 77, any correct      C
C FORTRAN 77 program can be compiled and executed successfully, on     C
C the Cyber 205. Use of the BLAS subprograms can improve the           C
C readability, portability and efficiency of your programs.            C
C When using these vectorized BLAS a great part of the execution       C
C can be performed at vector speed. If N is sufficiently large (N>50)  C
C the execution time will decrease extremely as compared with          C
C scalar execution.                                                    C
C                                                                      C
C An example of the control statements needed for execution on the     C
C Cyber 205.                                                           C
C                                                                      C
C     ATTACH,OLDLIB.                                                   C
C     FTN200,I=PROGRAM.                                                C
C     LOAD,LIB=OLDLIB,GRLPALL= ,L=O.                                   C
C     GO.                                                              C
C                                                                      C
C The file PROGRAM is translated by the FTN200 compiler. The used      C
C subprograms included in the library OLDLIB are loaded, and the       C
C binary code is executed. The parameter GRLPALL indicates that all    C
C modules, data base and common blocks are grouped and mapped on       C
C large page boundary.                                                 C
C                                                                      C
C For more information about the control statements, see [7].          C
C                                                                      C
C -------------------------------------------------------------------- C
C                                                                      C
      RETURN
      END
