flib.gml

开放源码的编译器open watcom 1.6.0版的源代码

.chap *refid=flib The &cmpname Subprogram Library
.*
.np
&product includes additional FORTRAN subprograms which can be called
from programs compiled by &cmpname..
The following sections describe these subprograms.
.*
.section Subroutine FEXIT
.*
.np
.ix 'subprograms' 'FEXIT subroutine'
.ix 'utility subprograms' 'FEXIT subroutine'
.ix 'FEXIT subroutine'
.ix 'return code'
.ix 'exiting with return code'
The subroutine
.id FEXIT
allows an application to terminate execution with a return code.
It requires one argument of type INTEGER that represents the value to
be returned to the system.
.exam begin
      INCLUDE 'FSUBLIB.FI'
      CALL FEXIT( -1 )
      END
.exam end
.autonote Notes:
.note
The FORTRAN include file :FNAME.fsublib.fi:eFNAME., located in the
:FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory, contains typing
and calling information for this subprogram.
The :FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory should be
included in the
.ev &incvarup
environment variable so that the compiler can locate the include file.
.endnote
.*
.section INTEGER Function FGETCMD
.*
.np
.ix 'subprograms' 'FGETCMD function'
.ix 'utility subprograms' 'FGETCMD function'
.ix 'FGETCMD function'
.ix 'command line'
.ix 'arguments'
The INTEGER function
.id FGETCMD
allows an application to obtain the command line from
within an executing program.
.np
The function
.id FGETCMD
requires one argument of type CHARACTER and returns the length of the
command line.
.exam begin
      INCLUDE 'FSUBLIB.FI'
      INTEGER CMDLEN
      CHARACTER*128 CMDLIN

      CMDLEN = FGETCMD( CMDLIN )
      PRINT *, 'Command length = ', CMDLEN
      PRINT *, 'Command line   = ', CMDLIN
      END
.exam end
.autonote Notes:
.note
The FORTRAN include file :FNAME.fsublib.fi:eFNAME., located in the
:FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory, contains typing
and calling information for this subprogram.
The :FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory should be
included in the
.ev &incvarup
environment variable so that the compiler can locate the include file.
.note
If the argument to
.id FGETCMD
is not long enough then only the first part of the command
line is returned.
.endnote
.*
.section INTEGER Function FGETENV
.*
.np
.ix 'subprograms' 'FGETENV function'
.ix 'utility subprograms' 'FGETENV function'
.ix 'FGETENV function'
The INTEGER function
.id FGETENV
allows an application to obtain the value of an
environment string from within an executing program.
.np
The function
.id FGETENV
requires two arguments of type CHARACTER.
The first argument is the character string to look for.
.id FGETENV
places the associated environment string value in the second argument
and returns the length of the environment string.
If no such string is defined, the length returned is zero.
.exam begin
      INCLUDE 'FSUBLIB.FI'
      INTEGER STRLEN
      CHARACTER*80 STRVAL

      STRLEN = FGETENV( 'PATH', STRVAL )
      PRINT *, 'Environment string length = ', STRLEN
      PRINT *, 'Environment string value  = ', STRVAL
      END
.exam end
.autonote Notes:
.note
The FORTRAN include file :FNAME.fsublib.fi:eFNAME., located in the
:FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory, contains typing
and calling information for this subprogram.
The :FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory should be
included in the
.ev &incvarup
environment variable so that the compiler can locate the include file.
.note
If the second argument to
.id FGETENV
is not long enough then only the first part of the value
is returned.
.endnote
.*
.section INTEGER Function FILESIZE
.*
.np
.ix 'subprograms' 'FILESIZE'
.ix 'utility subprograms' 'FILESIZE'
.ix 'FILESIZE'
The INTEGER function
.id FILESIZE
allows an application to determine the size of a file connected to a
specified unit.
.np
The function
.id FILESIZE
requires one argument of type INTEGER, the unit number and returns the
size, in bytes, of the file.
If no file is connected to the specified unit, a value of -1 is
returned.
.exam begin
      INCLUDE 'FSUBLIB.FI'

      OPEN( UNIT=1, FILE=':FNAME.sample.fil:eFNAME.' )
      PRINT *, FILESIZE( 1 )
      END
.exam end
.autonote Notes:
.note
The FORTRAN include file :FNAME.fsublib.fi:eFNAME., located in the
:FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory, contains typing
and calling information for this subprogram.
The :FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory should be
included in the
.ev &incvarup
environment variable so that the compiler can locate the include file.
.endnote
.*
.section Subroutine FINTR
.*
.np
.ix 'assembler subprograms' 'subroutine FINTR'
.ix 'utility subprograms' 'subroutine FINTR'
.ix 'FINTR subroutine'
The subroutine
.id FINTR
allows the user to execute any software interrupt from a
FORTRAN 77 program.
.remark
This subroutine is only supported by the DOS and Windows libraries.
.eremark
.np
The subroutine
.id FINTR
requires two arguments.
.autopoint
.point
The first argument is an interrupt number.
The subroutine
.id FINTR
will generate the software interrupt given by the first argument.
The type of this argument must be
.id INTEGER.
.point
The second argument is an
.id INTEGER
array of ten elements.
.endpoint
.np
When
.id FINTR
is called, the array contains the values to be assigned to the
registers prior to issuing the software interrupt.
When control is returned from
.id FINTR,
it contains the values of the registers after the software interrupt
has completed.
The registers are mapped onto the array
.id REGS
as follows.
.millust begin
            31      0
REGS(1)         EAX
REGS(2)         EBX
REGS(3)         ECX
REGS(4)         EDX
REGS(5)         EBP
REGS(6)         ESI
REGS(7)         EDI
REGS(8)       FS | DS
REGS(9)       GS | ES
REGS(10)      eflags
.millust end
.np
For 16-bit systems (e.g., 8088, 8086, 186, 286), only the low-order
16 bits of each register contain meaningful results.
.millust begin
            31      0
REGS(1)           AX
REGS(2)           BX
REGS(3)           CX
REGS(4)           DX
REGS(5)           BP
REGS(6)           SI
REGS(7)           DI
REGS(8)           DS
REGS(9)           ES
REGS(10)       flags
.millust end
.np
The file :FNAME.dos&hxt:eFNAME., located in the
:FNAME.&pathnamup.&pc.src&pc.fortran&pc.dos:eFNAME.
directory, defines a set of equivalences for
ease of use.
The contents of this file are reproduced below.
.code begin
* Define registers: These correspond to the element of an
* array which is to contain the values of the registers.

      integer*4 regd(10), regs(10)
      integer*2 regw(2*10)
      integer*1 regb(4*4)

      integer*4 EAX,EBX,ECX,EDX,EBP,EDI,ESI,EFLAGS
      integer*2 AX,BX,CX,DX,BP,DI,SI,DS,ES,FS,GS,FLAGS
      integer*1 AH,AL,BH,BL,CH,CL,DH,DL
      equivalence (regd,regs),(regd,regw),(regd,regb),
     1(EAX,regd(1)), (EBX,regd(2)), (ECX,regd(3)), (EDX,regd(4)),
     2(EBP,regd(5)), (EDI,regd(6)), (ESI,regd(7)), (EFLAGS,regd(10)),
     3(AX,regw(1)),  (BX,regw(3)),  (CX,regw(5)),  (DX,regw(7)),
     4(BP,regw(9)),  (DI,regw(11)), (SI,regw(13)), (DS,regw(15)),
     5(FS,regw(16)), (ES,regw(17)), (GS,regw(18)), (FLAGS,regw(19)),
     6(AL,regb(1)),  (AH,regb(2)),  (BL,regb(5)),  (BH,regb(6)),
     7(CL,regb(9)),  (CH,regb(10)), (DL,regb(13)), (DH,regb(14))
.code end
.np
The following is extracted from the "CALENDAR" program.
It demonstrates the use of the
.id FINTR
subroutine.
.code begin
      subroutine ClearScreen()
*$noextensions
      implicit none

      include 'dos&hxt'

* Define BIOS functions.

      integer VIDEO_CALL, SCROLL_UP
      parameter (VIDEO_CALL=16, SCROLL_UP=6)

      DS = ES = FS = GS = 0
      AH = SCROLL_UP            ! scroll up
      AL = 0                    ! blank entire window
      CX = 0                    ! set row,column of upper left
      DX = 24*256 + 80          ! set row,column of lower right
      BH = 7                    ! attribute "white on black"
      call fintr( VIDEO_CALL, regs )
      end
.code end
.*
.section INTEGER Function FLUSHUNIT
.*
.np
.ix 'subprograms' 'FLUSHUNIT function'
.ix 'utility subprograms' 'FLUSHUNIT function'
.ix 'FLUSHUNIT function'
The INTEGER function
.id FLUSHUNIT
flushes the internal input/output buffer for a specified unit.
Each file, except special devices such as :FNAME.con:eFNAME., has an
internal buffer.
Buffered input/output is much more efficient since it reduces the
number of system calls which are usually quite expensive.
For example, many
.kw WRITE
operations may be required before filling the internal
file buffer and data is physically transferred to the file.
.np
This function is particularly useful for applications that call
non-FORTRAN subroutines or functions that wish to perform input/output
to a FORTRAN file.
.np
The function
.id FLUSHUNIT
requires one argument, the unit number, of type INTEGER.
It returns an INTEGER value representing the return code of the
input/output operation.
A return value of 0 indicates success; otherwise an error occurred.
.np
The following example will flush the contents of the internal
input/output buffer for unit 7.
.exam begin
      INCLUDE 'FSUBLIB.FI'
      INTEGER ISTAT

      ISTAT = FLUSHUNIT( 7 )
      IF( ISTAT .NE. 0 )THEN
          PRINT *, 'Error in FLUSHUNIT'
      END IF

      END
.exam end
.autonote Notes:
.note
The FORTRAN include file :FNAME.fsublib.fi:eFNAME., located in the
:FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory, contains typing
and calling information for this subprogram.
The :FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory should be
included in the
.ev &incvarup
environment variable so that the compiler can locate the include file.
.endnote
.*
.section INTEGER Function FNEXTRECL
.*
.np
.ix 'subprograms' 'FNEXTRECL function'
.ix 'utility subprograms' 'FNEXTRECL function'
.ix 'FNEXTRECL function'
The INTEGER function
.id FNEXTRECL
reports the record length of the next unformatted record to be read
sequentially from the specified unit.
.np
The function
.id FNEXTRECL
requires one argument, the unit number, of type INTEGER.
It returns an INTEGER value representing the size of the next record
to be read.
.np
The following example creates an unformatted file and then reads the
records in the file sequentially.
.exam begin
      INCLUDE 'FSUBLIB.FI'

      CHARACTER*80 INPUT

      OPEN(UNIT=2, FILE='UNFORM.TXT', FORM='UNFORMATTED',
     & ACCESS='SEQUENTIAL' )
      WRITE( UNIT=2 ) 'A somewhat longish first record'
      WRITE( UNIT=2 ) 'A short second record'
      WRITE( UNIT=2 ) 'A very, very much longer third record'
      CLOSE( UNIT=2 )

      OPEN(UNIT=2, FILE='UNFORM.TXT', FORM='UNFORMATTED',
     & ACCESS='SEQUENTIAL' )

      I = FNEXTRECL( 2 )
      PRINT *, 'Record length=', I
      READ( UNIT=2 ) INPUT(1:I)
      PRINT *, INPUT(1:I)

      I = FNEXTRECL( 2 )
      PRINT *, 'Record length=', I
      READ( UNIT=2 ) INPUT(1:I)
      PRINT *, INPUT(1:I)

      I = FNEXTRECL( 2 )
      PRINT *, 'Record length=', I
      READ( UNIT=2 ) INPUT(1:I)
      PRINT *, INPUT(1:I)
      CLOSE( UNIT=2 )
      END
.exam end
.autonote Notes:
.note
The FORTRAN include file :FNAME.fsublib.fi:eFNAME., located in the
:FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory, contains typing
and calling information for this subprogram.
The :FNAME.&pathnam.&pc.src&pc.fortran:eFNAME. directory should be
included in the
.ev &incvarup
environment variable so that the compiler can locate the include file.
.endnote
.*
.if '&cmpclass' ne 'load-n-go' .do begin
.*
.section INTEGER Function FSIGNAL
.*
.np