Intel® Fortran Compiler 17.0 Developer Guide and Reference
You can use the USEROPEN specifier in an OPEN statement to pass control to a routine that directly opens a file. The called routine can use system calls or library routines to open the file and may establish special context that changes the effect of subsequent I/O statements.
The Intel® Fortran Run-Time Library (RTL) I/O support routines call the USEROPEN function in place of the system calls usually used when the file is first opened for I/O. The USEROPEN specifier in an OPEN statement specifies the name of a function to receive control.
The called function must open a file (or pipe) and return the file descriptor of the file (or pipe) it has opened when control is returned to the RTL. The called function may specify different options when it opens the file than a normal OPEN statement would. It may specify a different file.
You can obtain the file descriptor from the Intel® Fortran RTL for a specific unit number by using the PXFFILENO routine.
Although the called function can be written in other languages (such as Fortran), C is usually the best choice for making system calls, such as open or create.
If your application requires that you use C to perform the file open and close, as well as all record operations, call the appropriate C procedure from the Intel® Fortran program without using the Fortran OPEN statement.
If a filename has been specified in the OPEN statement that included the USEROPEN specifier, any subsequent CLOSE statement specifying STATUS=DELETE (or DISPOSE=DELETE) only acts on the filename specified in the OPEN statement. If you specified a different filename in the function named in USEROPEN, the CLOSE statement will have no effect on that filename.
The USEROPEN specifier for the OPEN statement has the form:
USEROPEN = function-name
The function-name represents the name of an external function. In the calling program, the function must be declared in an EXTERNAL statement. For example, the following Intel® Fortran code might be used to call the USEROPEN procedure UOPEN (known to the linker as uopen_):
EXTERNAL UOPEN
INTEGER UOPEN
.
.
.
OPEN (UNIT=10, FILE='/usr/test/data', STATUS='NEW', USEROPEN=UOPEN)During the execution of the OPEN statement, the external procedure called uopen_ receives control. The function opens the file, may perform other operations, and subsequently returns control (with the file descriptor) to the RTL. You can use other system calls or library routines within the USEROPEN function.
In most cases, the USEROPEN function modifies the open flags argument passed by the Intel® Fortran RTL or uses a new value before the open (or create) system call. After the function opens the file, it must return control to the RTL.
If the USEROPEN function is written in C, declare it as a C function that returns a 4-byte integer (int) result to contain the file descriptor.
If the USEROPEN function is written in Fortran, declare it as a FUNCTION with an INTEGER (KIND=4) result, perhaps with an interface block. In any case, the called function must return the file descriptor as a 4-byte integer to the RTL.
The following shows the available arguments and definitions for Linux* and OS X*, and then for Windows*:
Linux* and OS X* Arguments and Definitions:
int uopen_ ( (1) char *file_name, (2) int *open_flags, (3) int *create_mode, (4) int *lun, (5) int file_length); (6)
On Linux* and OS X* systems, the function definition and the arguments passed from the Intel® Fortran RTL are as follows:
The function must be declared as a 4-byte integer (int).
Indicates the pathname to be opened; the pathname includes the file name.
Indicates the open flags. The open flags are described in the header file /usr/include/sys/file.h or open(2).
Indicates the create mode, which is the protection needed when creating a Linux* OS-style file. The create modes are described in open(2).
Indicates the logical unit number.
Indicates the pathname length (hidden character length argument of the pathname).
Argument Notes for Linux* and OS X*:
The open system call (see open(2)) requires the passed pathname, the open flags (which define the type access needed, whether the file exists, and so on), and the create mode. The logical unit number specified in the OPEN statement is passed in case the USEROPEN function needs it. The hidden character length of the pathname is also passed.
Windows* Arguments and Definitions:
int uopen_ ( (1) char *filename, (2) int *desired_access, (3) int *share_mode, (4) int a_null, /* always 0 */ (5) int *flags_attr, (6) int b_null, /* always 0 */ (7) int *unit, (8) int *flen); (9)
On Windows* systems, the function definition and the arguments passed from the Intel® Fortran RTL are as follows:
The function must be declared as a 4-byte integer (int).
Indicates the pathname to be opened; the pathname includes the file name.
Indicates the mode of access. It can be set to read, write, or read/write.
Indicates the file protection mode.
This is a NULL that is passed as a literal zero by value.
This sets flags that specify file modes and several kinds of file features (such as whether to use sequential access or random access, whether to delete on close, etc.)
This is a NULL that is passed as a literal zero by value.
Indicates the logical unit number.
Indicates the pathname length (the hidden character length argument of the pathname).
Argument Notes for Windows*:
The argument list for a USEROPEN routine on Windows is very similar to the argument list for the Microsoft* Windows function CreateFile. This lets you easily write a USEROPEN routine and pass the input arguments to a call to CreateFile. The CreateFile system call requires the filename, the desired_access, the shared_mode, and the flags_attr. These arguments have been set to reflect the file semantics requested in the OPEN statement. The logical unit number specified in the OPEN statement is passed in case the USEROPEN function needs it. The hidden character length of the pathname is also passed.
On 32-bit Windows*, a Fortran USEROPEN function must use the default "C, Reference" calling convention. If you have used the iface compiler option to change the default calling convention to "stdcall" or "cvf", you will need to add a !DIR$ ATTRIBUTES DEFAULT directive in the function source to have it use the correct calling convention.
The Intel® Fortran RTL uses exactly one file descriptor per logical unit, which must be returned by the called function. Because of this, only certain system calls or library routines can be used to open the file.
On Linux* systems, system calls and library routines that do not return a file descriptor include mknod (see mknod(2)) and fopen (see fopen(3)). For example, the fopen routine returns a file pointer instead of a file descriptor.
The following Intel® Fortran code calls the USEROPEN function named UOPEN:
EXTERNAL UOPEN
INTEGER UOPEN
.
.
.
OPEN (UNIT=1,FILE='ex1.dat',STATUS='NEW',USEROPEN=UOPEN,
ERR=9,IOSTAT=errnum)If UOPEN is a Fortran function, its name is decorated appropriately for Fortran.
Likewise, if UOPEN is a C function, its name is decorated appropriately for C, as long as the following line is included in the above code:
!DIR$ ATTRIBUTES C::UOPENUse the icc or icl command to compile the called uopen C function uopen.c, and the ifort command to compile the Intel® Fortran calling program ex1.f. The same ifort command also links both object files by using the appropriate libraries:
icc -c uopen.c (Linux* OS)
icl -c uopen.c (Windows* OS)
ifort ex1.f uopen.o program UserOpenSample
IMPLICIT NONE
EXTERNAL UOPEN
INTEGER(4) UOPEN
CHARACTER*10 :: FileName="UOPEN.DAT"
INTEGER*4 :: IOS
Character*255 :: InqFullName
Character*100 :: InqFileName
Integer :: InqLun
Character*30 :: WriteOutBuffer="Write_One_Record_to_the_File. "
Character*30 :: ReadInBuffer ="??????????????????????????????"
110 FORMAT( X,A, ": Created (iostat=",I0,")")
115 FORMAT( X,A, ": Creation Failed (iostat=",I0,")")
120 FORMAT( X,A, ": ERROR: INQUIRE Returned Wrong FileName")
130 FORMAT( X,A, ": ERROR: ReadIn and WriteOut Buffers Do Not Match")
190 FORMAT( X,A, ": Completed.")
WRITE(*,'(X,"Test the USEROPEN Facility of Open")')
OPEN(UNIT=10,FILE='UOPEN.DAT',STATUS='REPLACE',USEROPEN=UOPEN, &
IOSTAT=ios, ACTION='READWRITE')
! When the OPEN statement is executed,
! the UOPEN function receives control.
! The function opens the file by calling CreateFile( ),
! performs whatever operations were specified, and subsequently
! returns control (with the handle returned by CreateFile( ))
! to the calling Fortran program.
IF (IOS .EQ. 0) THEN
WRITE(*,110) TRIM(FileName), IOS
INQUIRE(10, NAME=InqFullName)
CALL ParseForFileName(InqFullName,InqFileName)
IF (InqFileName .NE. FileName) THEN
WRITE(*,120) TRIM(FileName)
END IF
ELSE
WRITE(*,115) TRIM(FileName), IOS
GOTO 9999
END IF
WRITE(10,*) WriteOutBuffer
REWIND(10)
READ(10,*) ReadInBuffer
IF (ReadInBuffer .NE. WriteOutbuffer) THEN
WRITE(*,130) TRIM(FileName)
END IF
CLOSE(10, DISPOSE='DELETE')
WRITE(*,190) TRIM(FileName)
WRITE(*,'(X,"Test of USEROPEN Completed")')
9999 CONTINUE
END
!DIR$ IF DEFINED(_WIN32)
!+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
! Here is the UOPEN function for WIN32:
!
! The UOPEN function is declared to use the default calling convention,
! so it matches the Fortran RTL declaration of a USEROPEN routine.
!
! The following function definition and arguments are passed from the Intel
! Fortran® Run-time Library to the function named in USEROPEN:
!
! The first 7 arguments correspond to the CreateFile( ) API arguments.
! The value of these arguments is set according the caller's OPEN( )
! arguments:
!
! FILENAME
! Is the address of a null-terminated character string that
! is the name of the file.
! DESIRED_ACCESS
! Is the desired access (read-write) mode passed by reference.
! SHARE_MODE
! Is the file sharing mode passed by reference.
! A_NULL
! Is always null. The Fortran runtime library always passes a NULL
! for the pointer to a SECURITY_ATTRIBUTES structure in its
! CreateFile( ) call.
! CREATE_DISP
! Is the creation disposition specifying what action to take on files
! that exist, and what action to take on files that do not exist.
! It is passed by reference.
! FLAGS_ATTR
! Specifies the file attributes and flags for the file. It is passed
! by reference.
! B_NULL
! Is always null. The Fortran runtime library always passes a NULL
! for the handle to a template file in its CreateFile( ) call.
!
! The last 2 arguments are the Fortran unit number and length of the
! file name:
! UNIT
! Is the Fortran unit number on which this OPEN is being done. It is
! passed by reference.
! FLEN
! Is the length of the file name, not counting the terminating null.
! It is passed by value.
!+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
INTEGER(4) FUNCTION UOPEN( FILENAME, &
DESIRED_ACCESS, &
SHARE_MODE, &
A_NULL, &
CREATE_DISP, &
FLAGS_ATTR, &
B_NULL, &
UNIT, &
FLEN )
!DIR$ ATTRIBUTES DEFAULT :: UOPEN
USE KERNEL32
IMPLICIT NONE
INTEGER(4) DESIRED_ACCESS
INTEGER(4) SHARE_MODE
INTEGER(4) A_NULL
INTEGER(4) CREATE_DISP
INTEGER(4) FLAGS_ATTR
INTEGER(4) B_NULL
INTEGER(4) UNIT
INTEGER(4) FLEN
CHARACTER*(FLEN) FILENAME
INTEGER(4) ISTAT
TYPE(T_SECURITY_ATTRIBUTES), POINTER :: NULL_SEC_ATTR
140 FORMAT( X, "ERROR: USEROPEN Passed Wrong Unit Number",I)
! Sanity check
IF (UNIT .NE. 10) THEN
WRITE(*,140) UNIT
END IF
!! WRITE(*,*) "FILENAME=",FILENAME !! prints the full path of the filename
! Set the FILE_FLAG_WRITE_THROUGH bit in the flag attributes to CreateFile( )
! (for whatever reason)
! FLAGS_ATTR = FLAGS_ATTR + FILE_FLAG_WRITE_THROUGH
! Do the CreateFile( ) call and return the status to the Fortran rtl
ISTAT = CreateFile( FILENAME, &
DESIRED_ACCESS, &
SHARE_MODE, &
NULL_SEC_ATTR, &
CREATE_DISP, &
FLAGS_ATTR, &
0 )
if (ISTAT == INVALID_HANDLE_VALUE) then
write(*,*) "Could not open file (error ", GetLastError(),")"
endif
UOPEN = ISTAT
RETURN
END
!DIR$ ELSE ! LINUX OS or OS X
!+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
! Here is the UOPEN function for Linux OS/OS X:
!
! The UOPEN function is declared to use the cdecl calling convention,
! so it matches the Fortran RTL declaration of a USEROPEN routine.
!
! The following function definition and arguments are passed from the
! Intel® Fortran Run-time Library to the function named in USEROPEN:
!
! FILENAME
! Is the address of a null-terminated character string that is
! the name of the file.
! OPEN_FLAGS
! read-write flags (see file.h or open(2)).
! CREATE_MODE
! set if new file (to be created).
! UNIT
! Is the Fortran unit number on which this OPEN is being done. It is
! passed by reference.
! FLEN
! Is the length of the file name, not counting the terminating null.
! It is passed by value.
!+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
INTEGER(4) FUNCTION UOPEN( FILENAME, &
OPEN_FLAGS, &
CREATE_MODE, &
UNIT, &
FLEN )
IMPLICIT NONE
INTEGER(4) OPEN_FLAGS
INTEGER(4) CREATE_MODE
INTEGER(4) UNIT
INTEGER(4) FLEN
CHARACTER*(FLEN) FILENAME
INTEGER(4) ISTAT
!DIR$ ATTRIBUTES C, DECORATE, ALIAS:'open' :: OPEN
external OPEN
INTEGER(4) OPEN
140 FORMAT( X, "ERROR: USEROPEN Passed Wrong Unit Number",I)
! Sanity check
IF (UNIT .NE. 10) THEN
WRITE(*,140) UNIT
END IF
! Call the system OPEN routine
ISTAT = OPEN ( %ref(FILENAME), &
OPEN_FLAGS, &
CREATE_MODE )
UOPEN = ISTAT
RETURN
END
!DIR$ ENDIF ! End of UOPEN Function
!---------------------------------------------------------------
! SUBROUTINE: ParseForFileName
! Takes a full pathname and returns the filename
! with its extension.
!---------------------------------------------------------------
SUBROUTINE ParseForFileName(FullName,FileName)
Character*255 :: FullName
Character*100 :: FileName
Integer :: P
!DIR$ IF DEFINED(_WIN32)
P = INDEX(FullName,'\',.TRUE.)
FileName = FullName(P+1:)
!DIR$ ELSE ! LINUX OS/OS X
P = INDEX(FullName,'/',.TRUE.)
FileName = FullName(P+1:)
!DIR$ ENDIF
END