HP OpenVMS Systems Documentation

HP Fortran for OpenVMS
User Manual

Use of the USEROPEN keyword has some restrictions. The Run-Time Library constructs the following RMS control structures before calling the USEROPEN procedure:

A USEROPEN procedure should not alter the allocation of these structures, although it can modify the contents of many of the fields. Your procedure can also add additional XAB control blocks by linking them anywhere into the XAB chain. You must exercise caution when changing fields that have been set as a result of HP Fortran keywords, because the Run-Time Library may not be aware of the changes. For example, do not attempt to change the record size in your USEROPEN procedure; instead, use the HP Fortran keyword RECL. Always use an OPEN statement keyword if one is available.

Although the FAB, RAB, and NAM blocks remain defined during the time that the unit is opened, the XAB blocks are present only until the file has been successfully opened. The locations of the ESA and RSA strings are changed after the file is opened, so your USEROPEN procedure should not store the addresses of the RMS control structures. Instead, have your program call FOR$RAB to obtain the address of the RAB once the file is opened and then access the other structures through the RAB.

Table 11-1 shows which FAB and RAB fields are either initialized before your USEROPEN procedure is called or examined upon return from your USEROPEN procedure. All fields are initialized in response to OPEN statement keywords or default to zero. Fields labeled with a hyphen (-) are initialized to zero. Fields labeled with an asterisk (*) are returned by RMS.

RMS does not allow multiple instances of the same type XAB. To be compatible with future releases of the Run-Time Library, your procedure should scan the XAB chain for XABs of the type to be inserted. If one is found, it should be used instead.

11.5 Example of Block Mode I/O

The following example shows a complete application that calls the RMS block I/O services SYS$WRITE and SYS$READ directly from HP Fortran. A complete program called BIO.F90 writes out an array of REAL*8 values to a file using SYS$WRITE, closes the file, and then reads the data back in using SYS$READ operations with a different I/O transfer size. This program consists of five routines:

The following main program specifies the USEROPEN specifier in its OPEN statements.

!  File: BIO.F90
!
!       Program to demonstrate the use of RMS Block I/O operations
!       from HP Fortran

   PROGRAM BIO

!  Declare the Useropen routines as external

   EXTERNAL BIOCREATE, BIOREAD

!  Declare status variable, functions, and unit number

   LOGICAL (KIND=4)  STATUS, OUTPUT, INPUT
   INTEGER (KIND=4) IUN/1/

!       Open the file                                   (1)

   OPEN(UNIT=IUN, FILE='BIODEMO.DAT', FORM='UNFORMATTED', &
     STATUS='NEW', RECL=128, BLOCKSIZE=512, ORGANIZATION='SEQUENTIAL', &
     IOSTAT=IOS,  ACCESS='SEQUENTIAL', RECORDTYPE='FIXED',  &
     USEROPEN=BIOCREATE, INITIALSIZE=100)

   IF (IOS .NE. 0) STOP 'Create failed'                 (2)

!       Now perform the output

   STATUS = OUTPUT(%VAL(FOR$RAB(IUN)))                  (3)
   IF (.NOT. STATUS) STOP 'Output failed'               (2)

!       Close the file for output

   CLOSE (UNIT=IUN)

!  Confirm output complete

   TYPE *, 'Output complete, file closed'

!  Now open the file for input                          (2)

   OPEN(UNIT=IUN, FILE='BIODEMO.DAT', FORM='UNFORMATTED',  &
     STATUS='OLD', IOSTAT=IOS, USEROPEN=BIOREAD, DISP='DELETE')

   IF (IOS .NE. 0) STOP 'Open for read failed'          (2)

!       Now read the file back

   STATUS = INPUT(%VAL(FOR$RAB(IUN)))                   (3)
   IF (.NOT. STATUS) STOP 'Input failed'                (2)

!       Success, output that all is well

   STOP 'Correct completion of Block I/O demo'
   END PROGRAM BIO