HP OpenVMS Systems Documentation

Content starts here

HP Fortran for OpenVMS
User Manual


Previous Contents Index

11.4.2 RMS Control Structures

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

FAB File Access Block
RAB Record Access Block
NAM Name Block
XAB Extended Attributes Blocks
ESA Expanded String Area
RSA Resultant String Area

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.

Note

Future releases of the Run-Time Library may alter the use of some RMS fields. Therefore, you may have to alter your USEROPEN procedures accordingly.

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.

Table 11-1 RMS Fields Available with USEROPEN
Field Name Description HP Fortran OPEN Keyword and Value
FAB$B_ACMODES File access modes Contains FAB$V_CHAN_MODE and FAB$V_LNM_MODE.
FAB$L_ALQ Allocation quantity n if INITIALSIZE=n
FAB$B_BKS Bucket size (BLOCKSIZE + 511)/512
FAB$W_BLS Block size n if BLOCKSIZE=n
FAB$V_CHAN_MODE Channel access mode protection (2-bit subfield in FAB$B_ACMODES) 0=usermode
FAB$L_CTX Context --
FAB$W_DEQ Default file extension quantity n if EXTENDSIZE=n
FAB$L_DEV Device characteristics *
FAB$L_DNA Default file specification string
address
UNIT= nnn
Set to FOR nnn.DAT or FORREAD.DAT, FORACCEPT.DAT, FORTYPE.DAT, or FORPRINT.DAT or to default file specification string
FAB$B_DNS Default file specification string size Set to length of default file specification string
FAB$B_FAC File access READONLY
Set to 0 if READONLY (RMS default), else set to FAB$M_GET + FAB$M_PUT + FAB$M_UPD + FAB$M_TRN + FAB$M_DEL
FAB$L_FNA File specification string address FILE=filename if FILE present, else set to FOR nnn, FOR$READ, FOR$ACCEPT, FOR$TYPE, FOR$PRINT, SYS$INPUT, or SYS$OUTPUT
FAB$B_FNS File specification string size Set to length of file specification string
FAB$L_FOP File processing options  
FAB$V_ASY Asynchronous operation -- (not used)
FAB$V_CBT Contiguous best try 1 if INITIALSIZE=n
FAB$V_CIF Create if nonexistent 1 if READONLY not specified and STATUS='UNKNOWN' or STATUS omitted
FAB$V_CTG Contiguous allocation --
FAB$V_DFW Deferred write 1
FAB$V_DLT Delete on close service Set at Fortran close, depending upon DISP keyword in OPEN or CLOSE, or STATUS keyword in CLOSE
FAB$V_KFO Known file open --
FAB$V_MXV Maximize version number --
FAB$V_NAM Name block inputs --
FAB$V_NEF Not positioned at end of file 1 unless ACCESS= 'APPEND'
FAB$V_NFS Not file structured --
FAB$V_OFP Output file parse --
FAB$V_POS Current position (after closed file) --
FAB$V_PPF Process permanent file --
FAB$V_RCK Read check --
FAB$V_RWC Rewind on close service --
FAB$V_RWO Rewind on open service --
FAB$V_SCF Submit command (when closed) Set at Fortran close, depending upon DISP keyword in OPEN or CLOSE, or STATUS keyword in CLOSE
FAB$V_SPL Spool to printer Set at Fortran close, depending upon DISP keyword in OPEN or CLOSE, or STATUS keyword in CLOSE
FAB$V_SQO Sequential only 1 if a network file and ACCESS='SEQUENTIAL' or 'APPEND', else 0
FAB$V_SUP Supersede --
FAB$V_SYNCSTS Immediate asynchronous completion * (not used)
FAB$V_TEF Truncate at end-of-file --
FAB$V_TMD Temporary, marked for delete 1 if STATUS= 'SCRATCH', else 0
FAB$V_TMP Temporary (file with no directory
entry)
--
FAB$V_UFO User file open or create file only --
FAB$V_WCK Write check --
FAB$B_FSZ Fixed control area size --
FAB$W_IFI Internal file identifier *
FAB$W_GBC Global buffer count --
FAB$B_JOURNAL Journal flags status --
FAB$V_LNM_MODE Logical name translation access mode (subfield in FAB$B_ACMODES) --
FAB$L_MRN Maximum record number n if MAXREC=n
FAB$W_MRS Maximum record size n if RECORDTYPE='FIXED' or ORGANIZATION='RELATIVE' or ='INDEXED', else 0
FAB$L_NAM Name block address Set to address of name block; both the expanded and resultant string areas are set up, but the related filename string is not
FAB$B_ORG File organization FAB$C_IDX if ORGANIZATION='INDEXED'
FAB$C_REL if ORGANIZATION='RELATIVE'
FAB$C_SEQ if ORGANIZATION='SEQUENTIAL' or omitted
FAB$B_RAT Record attributes  
FAB$V_FTN Fortran carriage control 1 if CARRIAGECONTROL='FORTRAN' or not specified
FAB$V_CR Print LF and CR 1 if CARRIAGECONTROL='LIST'
FAB$V_BLK Do not cross block boundaries -- (1 if NOSPANBLOCKS)
FAB$B_RFM Record format FAB$C_FIX if RECORDTYPE='FIXED'
FAB$C_VAR if RECORDTYPE='VARIABLE'
FAB$C_VAR if RECORDTYPE='SEGMENTED'
FAB$C_STM if RECORDTYPE='STREAM'
FAB$C_STMCR if RECORDTYPE='STREAM_CR'
FAB$C_STMLF if RECORDTYPE='STREAM_LF'
FAB$B_RTV Retrieval window size --
FAB$L_SDC Spooling device characteristics *
FAB$B_SHR File sharing  
FAB$V_SHRPUT Allow other PUTs 1 if SHARED
FAB$V_SHRGET Allow other GETs 1 if SHARED
FAB$V_SHRDEL Allow other DELETEs 1 if SHARED
FAB$V_SHRUPD Allow other UPDATEs 1 if SHARED
FAB$V_NIL Allow no other operations --
FAB$V_UPI User-provided interlock --
FAB$V_MSE Multistream allowed --
FAB$L_STS Completion status code *
FAB$L_STV Status value *
FAB$L_XAB Extended attribute block address The XAB chain always has a File Header Characteristics (FHC) extended attribute block in order to get longest record length (XAB$W_LRL). If the KEY=keyword is specified, key index definition blocks will also be present. HP may add additional XABs in the future. Your USEROPEN procedure may insert XABs anywhere in the chain.
RAB$L_BKT Bucket code --
RAB$L_CTX Context --
RAB$L_FAB FAB address Set to address of FAB
RAB$W_ISI Internal stream ID *
RAB$L_KBF Key buffer address Set to address of longword containing logical record number if ACCESS='DIRECT'
RAB$B_KRF Key of reference 0
RAB$B_KSZ Key size --
RAB$B_MBC Multiblock count If BLOCKSIZE=n, use (n + 511)/512
RAB$B_MBF Multibuffer count n if BUFFERCOUNT=n
RAB$L_PBF Prompt buffer address --
RAB$B_PSZ Prompt buffer size --
RAB$B_RAC Record access mode  
RAB$C_KEY If ACCESS='DIRECT' or 'KEYED'  
RAB$C_SEQ If ACCESS='SEQUENTIAL' or 'APPEND', or ACCESS omitted  
RAB$C_RFA --  
RAB$L_RBF Record buffer address Set later
RAB$L_RFA Record file address Set later
RAB$L_RHB Record header buffer --
RAB$L_ROP Record processing options  
RAB$V_ASY Asynchronous --
RAB$V_BIO Block I/O --
RAB$V_CCO Cancel CTRL/O --
RAB$V_CVT Convert to uppercase --
RAB$V_EOF End-of-file 1 if ACCESS='APPEND'
RAB$V_ETO Extended terminal (XABTRM) operation --
RAB$V_FDL Fast delete --
RAB$V_KGE or
RAB$V_EQNXT
Key greater than or equal to --
RAB$V_KGT or
RAB$V_NXT
Key greater than --
RAB$V_LIM Limit --
RAB$V_LOA Load buckets according to fill size --
RAB$V_LOC Locate mode 1
RAB$V_NLK No lock --
RAB$V_NXR Nonexistent record --
RAB$V_PMT Prompt --
RAB$V_PTA Purge type-ahead --
RAB$V_RAH Read-ahead 1
RAB$V_REA Lock record for read --
RAB$V_RLK Lock record for write --
RAB$V_RNE Read no echo --
RAB$V_RNF Read no filter --
RAB$V_RRL Read regardless of lock --
RAB$V_SYNCSTS Immediate asynchronous completion * (not used)
RAB$V_TMO Timeout --
RAB$V_TPT Truncate on PUT 1
RAB$V_UIF Update if 1 if ACCESS='DIRECT'
RAB$V_ULK Manual unlocking --
RAB$V_WAT Wait for locked record --
RAB$V_WBH Write-behind 1
RAB$W_RSZ Record size Set later
RAB$L_STS Completion status code *
RAB$L_STV Status value *
RAB$B_TMO Timeout period --
RAB$L_UBF User record area address Set later
RAB$W_USZ User record area size Set later
RAB$L_XAB Extended attribute block address The XAB chain allows you to set or obtain additional information about an I/O operation.

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:

BIO Main control program
BIOCREATE USEROPEN routine to create the file
BIOREAD USEROPEN routine to open the file for READ access
OUTPUT Function that actually outputs the array
INPUT Function that actually reads the array and checks it

11.5.1 Main Block Mode I/O Program---BIO

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


Previous Next Contents Index