File FTNLIB.DC (file description)

Directory of image this file is from
This file as a plain text file


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------




                 Date of last documentation change  -   23-FEB-82



      This document describes routines contained in FTNLIB.RL.

      The  sources  for  these  routines are located on diskette RX8-8 in the
      FORT box.

      The source for this document is on diskette RX8-96 in the INFO box.


              CALL CAL (MTEXT,IDAY,IYEAR,DTEXT)

              CALL CAT (INFO)

              CALL CCL (TEXT)

              CALL DATE (IMON,IDAY,IYEAR)

              CALL DIR (IUNIT,DNAME)

              FR = DYDIM (NUM,LNGTH)

              CALL DYGET (VECTR,ILOW,IMAX,IBUFF)

              CALL DYPUT (VECTR,ILOW,IMAX,IBUFF)

              CALL DYRST

              FR = F4096 (IVAL)

              IR = IFCHN (ITEXT)

              IR = IFDIF (FVAL1,FVAL2)

              IR = IFIXR (FVAL)

              IR = INTFS (TEXT,DNAMO,FNAMO,DNAMI,FNAMI)

              IR = INVAL (IUNIT,LNGTH,TEXT,VAL)

              IR = ISWR (IBIT)

              IR = I4096 (FVAL)

              IR = LEX (STR1,STR2)

              CALL MOVE (BUFF1,BUFF2,LNGTH)

              CALL NUMB (FVAL or IVAL,TEXT,IWIDE,IDEC)

              FR = OCTA4 (IVAL)

              CALL PACK (TEXTI,TEXTO)



                                   1 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------


              FR = RAND (SEED)

              FR = RND (SEED)

              FR = STDEV (NVARS,SUM,SQRS)

              CALL UEXIT (ITYPE)

              CALL UNPAC (TEXTI,TEXTO)

              CALL VTCLR

              CALL VTESC (ICODE)

              CALL VTHOM

              CALL VTPOS (ICOL,IROW)

              CALL ZFILL (TEXT,LNGTH)

      -----------------------------------------------------------------------







































                                   2 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------


      CAL     Subroutine      Source: CAL.SB                  Date: 25-JUN-81

                      CALL CAL (MTEXT,IDAY,IYEAR,DTEXT)

                      MTEXT : Month in 5A2 format.
                      IDAY  : Day of month (1-31).
                      IYEAR : Calendar year (1977-1984).
                      DTEXT : Day of week in 5A2 format.

              Returns current date information derived from the OS/8 date.



      CAT     Subroutine      Source: DIR.SB                  Date: 01-JAN-82

                      CALL CAT (INFO)

                      INFO  : 9 word array into which  directory  information
                              is written.

              Returns next directory entry.

              Word    Contents
              ----    --------
               1-3    File name.  (See file name note below).
                4     Extension.
                5     Month (1-12).
                6     Day (1-31).
                7     Year (70-77).
                8     File length in blocks.
                9     File starting block.

              If  INFO(1)=0  then  entry is for an empty file. INFO(8) is the
              length.

              If INFO(1)=-1 then end of directory.

              See DIR  subroutine  for  selecting  which  device  from  which
              directory is to be read.



      CCL     Subroutine      Source: CCL.SB                  Date: 20-NOV-81

                      CALL CCL (TEXT)

                      TEXT  : Packed 6-bit text of CCL command.

              Chains  to  CCLX  which  then executes the command contained in
              TEXT. Since CCLX has no 'return to caller' feature, there is no
              return from this routine  (it  is  very  much  like  the  CHAIN
              routine).

              TEXT  must  be  in packed 6-bit (A2 format) with an ending '00'
              byte. Imbedded '@' characters are not allowed, since  they  are
              represented  by  a  '00'  code.  A maximum of 34 characters are
              allowed in the text.



                                   3 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------


              For  example,  CALL CCL('SUBMIT NAME@')  will  cause  the  same
              action as if the SUBMIT NAME command had been entered  via  the
              console.



      DATE    Subroutine      Source: DATE.FT                 Date: 25-JUN-81

                      CALL DATE (IMON,IDAY,IYEAR)

                      IMON  : Month (0-12).
                      IDAY  : Day of month (0-31).
                      IYEAR : Year (1970-2001).

              Returns the date maintained by OS/8.



      DIR     Subroutine      Source: DIR.SB                  Date: 01-JAN-82

                      CALL DIR (IUNIT,DNAME)

                      IUNIT : FORTRAN I/O unit number (4-5).
                      DNAME : Device name in 2A2 format.

              Initializes directory catalog reading from specified device via
              specified  I/O  unit.  That unit must not be used for any other
              purpose until the final call to CAT has been made.  The  device
              being  read  must  remain  in  the  drive because the directory
              blocks are read one at a time as they are needed.

              See CAT subroutine for reading the directory entries.



      DYDIM   Function        Source: DYN.SB                  Date: 12-AUG-81

                      VECTR = DYDIM (NUM,LNGTH)

                      NUM   : Number of elements  to  allocate  from  dynamic
                              storage.
                      LNGTH : Length in words of each element.

              Creates  a  dynamic  array  of  NUM elements of size LNGTH. For
              example, LNGTH = 1 is used for integer arrays, and LNGTH = 3 is
              used for real  arrays.  The  type  real  VECTR  value  returned
              contains  3  words  of  information used by the DYGET and DYPUT
              routines and is meaningless otherwise.

              VECTR = 0.0 if there was  insufficient  room  left  in  dynamic
              storage  to allocate the requested array. Otherwise it has some
              non-zero value.

              For example, to allocate and use a 10 element real array:






                                   4 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------


                      dimension array(9)

                      call dyrst
                      vect1 = dydim (10,3)
                      call dyput (vect1,1,1,3.14)     [1st el. = 3.14]
                      call dyput (vect1,2,10,array)   [2nd - 10th = array]
                      call dyget (vect1,1,1,pi)       [pi set to 3.14]

              See DYRST subroutine for info on initializing dynamic storage.



      DYGET   Subroutine      Source: DYN.SB                  Date: 12-AUG-81

                      CALL DYGET (VECTR,ILOW,IMAX,IBUFF)

                      VECTR : Real variable that holds info from DIM call.
                      ILOW  : Array index of first dynamic element to read.
                      IMAX  : Array index of last dynamic element to read.
                      BUFF  : Real or integer array into which data is to  be
                              written.

              Copies an array from dynamic to static storage.

              See DYDIM function for info about dynamic storage allocation.

              ERROR MESSAGES:

               VAL? : Invalid dynamic array vector or index out-of-range.



      DYPUT   Subroutine      Source: DYN.SB                  Date: 12-AUG-81

                      CALL DYPUT (VECTR,ILOW,IMAX,IBUFF)

                      VECTR : Real variable that holds info from DIM call.
                      ILOW  : Array index of first dynamic element to write.
                      IMAX  : Array index of last dynamic element to write.
                      BUFF  : Real  or integer array from which data is to be
                              read.

              Copies an array from static to dynamic storage.

              See DYDIM function for info about dynamic storage allocation.

              ERROR MESSAGES:

               VAL? : Invalid dynamic array vector or index out-of-range.



      DYRST   Subroutine      Source: DYN.SB                  Date: 12-AUG-81

                      CALL DYRST

              Resets dynamic storage allocation free  space  pointers.  DYRST
              must  be called before any calls to DYDIM are made in order for


                                   5 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------


              the free memory limits to be  determined.  DYRST  can  also  be
              called  after any DYDIM calls to reset the free space pointers.
              Any  vectors  allocated  up  until  then  can  no   longer   be
              referenced.

              Free  memory limits are determined by examining the 127th entry
              in the external symbol table. It is set by the loader  at  load
              time  to the highest address loaded. The remaining locations in
              that  field,  and  all  of  any  remaining  higher  fields  are
              available for  dynamic  storage  (except  for  07600-07777  and
              17600-17777 to avoid destroying system areas).

              See DYDIM function for info on dynamic storage allocation.



      F4096   Function        Source: CONVRT.SB               Date: 14-SEP-77

                      FVAL = F4096 (IVAL)

                      IVAL  : Integer value.

              Floats IVAL to a number from 0. to 4095. instead of from -2048.
              to 2047.



      IFCHN   Function        Source: IFCHN.SB                Date: 21-SEP-77

                      IFLAG = IFCHN (ITEXT)

                      ITEXT : 20 word buffer (40 characters) for parameter.
                      IFLAG : -1 if program chained to, 0 otherwise.

              Checks if program chained to, and constructs parameter text.

              The  parameter  is  retrieved from locations 17600 - 17646, one
              character per word. It is packed into 6-bit  character  format,
              ignoring  all  non-six-bit  set  characters.  The  remainder is
              zero-filled. A first word of zero indicates no parameter.

              The text can be put there  by  another  program,  or  by  using
              CCLX's  DEFINE  command,  and  subsequent  invocations  of  the
              program with a parameter. For example:

              .DEFINE PROG

              .PROG,PARAMETER TEXT

              The  IFCHN function would return a -1 for IFLAG, and "PARAMETER
              TEXT" in ITEXT. If PROG were just  run  normally,  IFCHN  would
              return a 0 for IFLAG.








                                   6 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------


      IFDIF   Function        Source: MISC1.SB                Date: 14-SEP-77

                      IFLAG = IFDIF (FVAL1,FVAL2)

                      FVAL1 : First value to compare.
                      FVAL2 : Second value to compare.
                      IFLAG : 0  if  FVAL1 equals FVAL2, or non-zero if FVAL1
                              differs from FVAL2.

              FVAL1  and  FVAL2   are   compared   without   using   floating
              subtraction.  This  function  is  designed  to be used for text
              string  comparisons.  Using  floating  subtraction  to  compare
              strings sometimes produces equalities where none exist due  to,
              for  example,  single character, zero-filled values. These will
              have a non-zero exponent, but a zero mantissa. Thus zero  minus
              zero is zero, which is an incorrect result.



      IFIXR   Function        Source: CONVRT.SB               Date: 16-SEP-77

                      IRSLT = IFIXR (FVAL)

                      FVAL  : Value to convert from real to integer.
                      IRSLT : Converted value.

              Converts   real  value  to  integer  by  rounding  off  decimal
              fraction. The IFIX function truncates instead of rounds.



      INTFS   Function        Source: INTFS.SB                Date: 20-NOV-81

                      IFLAG = INTFS (TEXT,DNAMO,FNAMO,DNAMI,FNAMI)

                      TEXT  : Text string containing  file  specification  to
                              interpret.
                      DNAMO : Text from output device name field of string.
                      FNAMO : Text from output file name field of string.
                      DNAMI : Text from input device name field of string.
                      FNAMI : Text from file name field of string.
                      IFLAG : Indicates  whether  or  not  interpretation was
                              successful.

              Interprets 6-bit zero-filled text and returns zero-filled  file
              specifications   along  with  a  code  indicating  whether  the
              interpretation was successful:

              IFLAG   Meaning
              -----   -------
               -1     Format error.
                0     Processed o.k., but more text followed on input side.
               +1     Processed o.k.

              TEXT  format  is  the  same  as  for   command   decoder   file
              specification  format.  In addition, a semicolon can be used in
              place of a colon, and a leading asterisk will be  allowed  (and
              ignored).


                                   7 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------



              For example:

              TEXT of 'TTY:<SYS:FILE.EX'

              returns the following values (@ is 00 code character):

              DNAMO = 'TTY@'
              FNAMO = '@@@@@@@@'
              DNAMI = 'SYS@'
              FNAMI = 'FILE@@EX'
              IFLAG = 1



      ISWR    Function        Source: ISWR.SB                 Date: 10-SEP-77

                      IVAL = ISWR (IBIT)

                      IBIT  : Bit number (1-12), or 0 if entire register.
                      IVAL  : 0 if Switch down, 1 if up.

              Reads  Switch  Register  on PDP8 front panel. IBIT value is one
              greater than bit position (e.g. IBIT = 1 reads bit 0).

              ERROR MESSAGES:

               B>12 : IBIT parameter was out of range.



      I4096   Function        Source: CONVRT.SB               Date: 14-SEP-77

                      IVAL = I4096 (FVAL)

                      FVAL  : Real value to convert.
                      IVAL  : Converted value.

              Integerizes real numbers without checking for  range  to  allow
              integerizing  numbers  outside  the  range  handled by the IFIX
              routine.



      LEX     Function        Source: LEX.SB                  Date: 15-SEP-77

                      IFLAG = LEX (STR1,STR2)

                      STR1  : First 12 character string to compare.
                      STR2  : Second 12 character string to compare.
                      IFLAG : Indicates lexicographical  order  of  STR1  and
                              STR2.

              Compares  two  12 character strings for lexicographic ordering.
              Strings are in packed 6-bit text format.





                                   8 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------


              IFLAG   Meaning
              -----   -------
               -1     STR1 precedes STR2 in lexicographical order.
                0     STR1 = STR2.
                1     STR2 precedes STR1 in lexicographical order.



      MOVE    Subroutine      Source: MISC1.SB                Date: 20-NOV-81

                      CALL MOVE (BUFF1,BUFF2,LNGTH)

                      BUFF1 : Source buffer.
                      BUFF2 : Destination buffer.
                      LNGTH : Count of words to move. Multiple of 3 for  real
                              values.

              Moves LNGTH consecutive words from BUFF1 to BUFF2.

              If LNGTH is negative, the absolute value is used for the number
              of  words,  and  the  move  terminates  when  a  '00' code ('@'
              character) is encountered in the bottom  character  of  a  word
              (any  remainder  in  BUFF2 is zero-filled). This can be used to
              move a text string of undetermined length into a buffer and not
              move any extra garbage in with it.



      NUMB    Subroutine      Source: NUMB.SB                 Date: 15-SEP-77

                      CALL NUMB (FVAL/IVAL,TEXT,IWIDE,IDEC)

                      FVAL  : Real value to convert if IDEC not -2.
                      IVAL  : Integer value to convert if IDEC = -2.
                      TEXT  : Text string returned (A1 format).
                      IWIDE : Number of characters desired in text string.
                      IDEC  : Number of places to the right  of  the  decimal
                              point.

              Converts  a  real  or  integer  value into its character string
              representation.  The  value  is  right-adjusted  with   leading
              blanks.  The  PACK  routine  can  be used to convert it from A1
              format to packed 6-bit (A2) format.

              The format can be controlled with IDEC as follows:

              IDEC    VAL type        Period in text?
              ----    --------        ---------------
               >0     Real            Yes, followed by IDEC decimal places.
                0     Real            Yes, as last character.
               -1     Real            No, one's digit is last character.
               -2     Integer         No, one's digit is last character.








                                   9 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------


      OCTA4   Function        Source: OCTA4.SB                Date: 14-SEP-77

                      TEXT = OCTA4 (IVAL)

                      IVAL  : Integer value.
                      TEXT  : A4 format  character  representation  of  octal
                              value.

              Returns four digit A4 format display code of the octal value.



      PACK    Subroutine      Source: CHAR.SB                 Date: 15-SEP-77

                      CALL PACK (TEXTI,TEXTO)

                      TEXTI : Input text string in 6A1 format.
                      TEXTO : Output text string in A6 format.

              Packs a text string.

              See UNPAC routine for inverse operation.



      RAND    Function        Source: (none)                  Date: 14-SEP-77

                      FVAL = RAND (SEED)

                      SEED  : 0 if next number desired, non-zero if seeding.
                      FVAL  : Next random number if SEED = 0.

              Seeds/calls random number generator. This subroutine is part of
              the binary file received from DECUS, catalog number 8-154.

              The  DECUS  writeup describing this routine is in the binder at
              the end of this section.

              See RND function for a different random number generator.



      RND     Function        Source: (none)                  Date: 14-SEP-77

                      FVAL = RND (SEED)

                      SEED  : 0 if next number desired, non-zero if seeding.
                      FVAL  : Next random number if SEED = 0.

              Seeds/calls random number generator. This subroutine is part of
              the binary file received from DECUS, catalog number 8-154.

              The DECUS writeup describing this routine is in the  binder  at
              the end of this section.

              See RAND function for a different random number generator.




                                   10 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------


      STDEV   Function        Source: STDEV.SB                Date: 14-SEP-77

                      FVAL = STDEV (NVARS,SUM,SQRS)

                      NVARS : Number of values summed up in SUM and SQRS.
                      SUM   : Sum of NPARS values.
                      SQRS  : Sum of squares of NPARS values.
                      FVAL  : Calculated standard deviation.

              Computes standard deviation from sum and sum of squares.

              The formula used to compute standard deviation is:

                              ---------------------------------
                             /  / NVARS * SQRS - SUM * SUM \
                        --  /  ( -------------------------- )
                          \/    \    NVARS * (NVARS -1)    /

              If NVARS is either 0 or 1, a STDEV of 0.0 is returned, although
              the result is technically undefined. The user should do his own
              checks for these cases.



      UEXIT   Subroutine      Source: UEXIT.SB                Date: 06-NOV-81

                      CALL UEXIT (ITYPE)

                      ITYPE : Indicates what type of user exit.

              Modifies  the  behavior of the FORTRAN run time system when the
              EXIT routine is called, which is in the following cases:

              1. When the FORTRAN instruction STOP is executed.
              2. When a Control-C is detected on the console keyboard.
              3. After a fatal error message is printed.

              The EXIT routine waits for any I/O in progress to complete, and
              then exits to the OS/8 system.

              The UEXIT routine can be used to regain control when the  above
              conditions occur.

              ITYPE   Action
              -----   ------
                0     Cancel User Exit (next EXIT will go to OS/8)
                1     EXIT calls will instead return from the last UEXIT call
                2     EXIT calls restart the program

              For example:

                      itrap = .false.
                      call uexit(1)
                      if (itrap) then
              c       code to handle trapped exits goes here
                      endif
              c       Otherwise, falls through the first time, only
                      itrap = .true.


                                   11 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------



              Note  that a CALL UEXIT(0) must be executed in order to exit to
              OS/8 after any other UEXIT calls have been made.



      UNPAC   Subroutine      Source: CHAR.SB                 Date: 15-SEP-77

                      CALL UNPAC (TEXTI,TEXTO)

                      TEXTI : Input text string in A6 format.
                      TEXTO : Output text string in 6A1 format.

              Unpacks a text string.

              See PACK routine for inverse operation.



      VTCLR   Subroutine      Source: VTSUB.SB                Date: 14-SEP-77

                      CALL VTCLR

              Clears VT50 screen from cursor  line  on  down  by  sending  an
              (ESC J) sequence (033 112) to FORTRAN unit 1.



      VTESC   Subroutine      Source: VTSUB.SB                Date: 14-SEP-77

                      CALL VTESC (ICODE)

                      ICODE : 1 byte code to follow ESC byte.

              Sends escape sequence (033) (ICODE) to FORTRAN unit 1.



      VTHOM   Subroutine      Source: VTSUB.SB                Date: 14-SEP-77

                      CALL VTHOM

              Positions  VT50  cursor  at  upper  left  corner  by sending an
              (ESC H) sequence (033 110) to FORTRAN unit 1.



      VTPOS   Subroutine      Source: VTSUB.SB                Date: 14-SEP-77

                      CALL VTPOS (ICOL,IROW)

                      ICOL  : Column number.
                      IROW  : Row number (row 1 is bottom row).

              Positions VT50 cursor at ICOL from left, IROW  from  bottom  by
              sending an (ESC Y 070-IROW 037+ICOL) sequence (033 131 0YY 0XX)
              to FORTRAN unit 1.



                                   12 


      ---------  FTNLIB Fortran Library Documentation (FTNLIB.TS)  ----------


      ZFILL   Function        Source: ZFILL.SB                Date: 14-SEP-77

                      CALL ZFILL (TEXT,LNGTH)

                      TEXT  : Text string to zero or space fill.
                      LNGTH : Length of string in words.

              If  LNGTH  is  positive, trailing spaces and zero codes will be
              converted to zero codes.

              If LNGTH is negative, trailing spaces and zero  codes  will  be
              converted  to  spaces with the absolute value of LNGTH taken as
              the length.

              This function is used primarily to  space-fill  and  zero  fill
              text  strings  such as file names. A subroutine might require a
              zero filled text argument but printout  requires  space  filled
              text  to avoid printing trailing 'at' (@) signs. ZFILL comes in
              handy for making the conversions between the two formats.









































                                   13 



Feel free to contact me, David Gesswein djg@pdp8online.com with any questions, comments on the web site, or if you have related equipment, documentation, software etc. you are willing to part with.  I am interested in anything PDP-8 related, computers, peripherals used with them, DEC or third party, or documentation. 

PDP-8 Home Page   PDP-8 Site Map   PDP-8 Site Search