HP OpenVMS Systems Documentation

HP Fortran for OpenVMS
User Manual

The DELETE statement allows you to delete records from an indexed file. The DELETE and REWRITE statements are similar; a record must first be locked by a READ statement before it can be operated on.

The following Fortran code segment deletes the second record in the file with ITEM_NUMBER 375 (refer to previous examples):

  READ (UNIT=10,KEY=375,KEYID=2,IOSTAT=IOS,ERR=9999)
  READ (UNIT=10,IOSTAT=IOS,ERR=9999) FILE_REC
  IF (FILE_REC.ITEM_NUMBER .EQ. 375) THEN
      DELETE (UNIT=10, IOSTAT=IOS, ERR=9999)
  ELSE
      PRINT *, 'There is no second record.'
  END IF

Deletion removes a record from all defined indexes in the file.

12.7 Current Record and Next Record Pointers

The RMS file system maintains two pointers into an open indexed file:

• The next record pointer indicates the record to be retrieved by a sequential read. When you open an indexed file, the next record pointer indicates the record with the lowest primary key field value. Subsequent sequential read operations cause the next record pointer to be the one with the next higher value in the same key field. In case of duplicate key field values, records are retrieved in the order in which they were written.
• The current record pointer indicates the record most recently retrieved by a READ operation; it is the record that is locked from access by other programs sharing the file.
  The current record is the one operated on by the REWRITE statement and the DELETE statement. The current record is undefined until a read operation is performed on the file. Any file operation other than a read causes the current record pointer to become undefined. Also, an error results if a rewrite or delete operation is performed when the current record pointer is undefined.

You can expect to encounter certain exception conditions when using indexed files. The two most common of these conditions involve valid attempts to read locked records and invalid attempts to create duplicate keys. Provisions for handling both of these situations should be included in a well-written program.

When an indexed file is shared by several users, any read operation may result in a "specified record locked" error. One way to recover from this error condition is to ask if the user would like to reattempt the read. If the user's response is positive, then the program can go back to the READ statement. For example:

    INCLUDE '($FORIOSDEF)'
 .
 .
 .

100  READ (UNIT=10,IOSTAT=IOS) DATA

   IF (IOS .EQ. FOR$IOS_SPERECLOC) THEN
     TYPE *, 'That record is locked. Press RETURN'
     TYPE *, 'to try again, or Ctrl/Z to discontinue'
     READ (UNIT=*,FMT=*,END=900)
     GO TO 100
   ELSE IF (IOS .NE. 0) THEN
     CALL ERROR (IOS)
   END IF

You should avoid looping back to the READ statement without first providing some type of delay (caused by a request to try again, or to discontinue, as in this example). If your program reads a record but does not intend to modify the record, you should place an UNLOCK statement immediately after the READ statement. This technique reduces the time that a record is locked and permits other programs to access the record.

The second exception condition, creation of duplicate keys, occurs when your program tries to create a record with a key field value that is already in use. When duplicate key field values are not desirable, you might have your program prompt for a new key field value whenever an attempt is made to create a duplicate. For example:

   INCLUDE '($FORIOSDEF)'

200  WRITE (UNIT=10,IOSTAT=IOS) KEY_VAL, DATA

   IF (IOS .EQ. FOR$IOS_INCKEYCHG) THEN
      TYPE *, 'This key field value already exists. Please'
      TYPE *, 'enter a different key field value, or press'
      TYPE *, 'Ctrl/Z to discontinue this operation.'
      READ (UNIT=*,FMT=300,END=999) KEY_VAL
      GO TO 200
   ELSE IF (IOS .NE. 0) THEN
      CALL ERROR (IOS)
   END IF

This chapter describes how to exchange and share data between local and remote processes:

• Section 13.1,HP Fortran Program Section Usage
• Section 13.2, Local Processes: Sharing and Exchanging Data
• Section 13.3, Remote Processes: Sharing and Exchanging Data

Local processes involve a single OpenVMS processor, and remote processes involve separate processors that are interconnected by means of DECnet.

13.1 HP Fortran Program Section Usage

You may need to change program section attributes to allow shared access to an installed shareable image.

The storage required by an HP Fortran program unit is allocated in contiguous areas called program sections (PSECTs). The HP Fortran compiler implicitly declares these PSECTs:

• $CODE$
• $DATA$
• $BSS$
• $LITERAL$
• $LINK$

Each common block you declare causes allocation of a PSECT with the same name as the common block. (The unnamed common block PSECT is named $BLANK.) Memory allocation and sharing are controlled by the linker according to the attributes of each PSECT; PSECT names and attributes are listed in Table 13-1.

Each procedure in your program is named according to the name specified in the PROGRAM, BLOCK DATA, FUNCTION, or SUBROUTINE statement used in creating the object module. The defaults applied to PROGRAM and BLOCK DATA statements are source-file-name$MAIN and source-file-name$DATA, respectively.

You can use the cDEC$ PSECT (such as !DEC$ PSECT) directive or use a linker options file to change some of the attributes of a common block.

Table 13-2 describes the meanings of HP Fortran PSECT attributes.

When the linker constructs an executable image, it divides the executable image into sections. Each image section contains PSECTs that have the same attributes. By arranging image sections according to PSECT attributes, the linker is able to control memory allocation. The linker allows you to allocate memory to your own specification by means of commands you include in an options file that is input to the linker.

For More Information:

• On the cDEC$ PSECT (!DEC$ PSECT) compiler directive statement, see the HP Fortran for OpenVMS Language Reference Manual.
• On examples of linker options files used for shared installed common data, see Section 13.2.2.
• On the linker options file and special program sections, see the HP OpenVMS Linker Utility Manual.

Interprocess communication mechanisms provided for local processes include the following capabilities:

• Program image sharing in shareable image libraries
• Data sharing in installed common areas
• Information passing by means of mailboxes
• Information passing over DECnet network links

These capabilities are discussed in the sections that follow.

VOLATILE declarations are required when you use certain run-time features of the operating system, including values that can be read or written by methods other than direct assignment, or during a routine call.

If a variable can be accessed using rules in addition to those provided by the standard Fortran 90/95 language, declare the variable as VOLATILE. For example, if a variable in COMMON can change value by means of an OpenVMS AST routine or condition handler, you must declare that common block variable or the entire COMMON block as volatile.

Consider the following uses of variables as candidates for a VOLATILE declaration if asynchronous access might occur:

• Variables in common blocks
• Variables in modules
• Addresses not saved by the %LOC built-in function
• Variables with the TARGET attribute
• Variables declared with the SAVE statement in recursive routines
• Dummy arguments
  Alternatively, if the only local accesses occur when the variable is passed as a dummy argument, the command-line option /ASSUME=DUMMY_ALIASES can be used instead of a VOLATILE declaration (see Section 5.8.9).
• Variables in shared global sections

If you have a routine that is invoked by more than one program, you should consider establishing it as a shareable image and installing it on your system.

Establishing a routine as a shareable image provides the following benefits:

• Saves disk space: The executable images to which the shareable image is linked do not actually include the shareable image. Only one copy of the shareable image exists.
• Simplifies maintenance: If you use symbol vectors, you can modify, recompile, and relink a shareable image without having to relink the executable images that reference it.

Installing a shareable image as shared (INSTALL command, /SHARED qualifier) can also save memory.

The steps to creating and installing a shareable image are:

1. Compile the source file containing that routine that you want to establish as a shareable image.
2. Link the shareable image object file that results from step 1, specifying any object files that contain routines referenced by the shareable image object file.
   The OpenVMS Linker provides a variety of options that you should consider before performing the link operation. For detailed information on shareable images and linker options, see the HP OpenVMS Linker Utility Manual.
3. Create a shareable image library using the Library Utility's LIBRARY command. For detailed information on creating shareable image libraries, see the Guide to Creating OpenVMS Modular Procedures.
4. Install the shareable image (the results of step 3) on your system as a shared image by using the Install Utility's INSTALL command (with the /SHARED qualifier). For detailed information on how to perform this operation, see the VMS Install Utility Manual.

Any programs that access a shareable image must be linked with that image. When performing the link operation, you must specify one of the following items on your LINK command:

• The name of the shareable image library containing the symbol table of the shareable image. Use the /LIBRARY qualifier to identify a library file.
• A linker options file that contains the name of the shareable image file. Use the /SHAREABLE qualifier to identify a shareable image file. (If you specify the /SHAREABLE qualifier on the LINK command line and you do not specify an options file, the linker creates a shareable image of the object file you are linking.)

The resulting executable image contains the contents of each object module and a pointer to each shareable image.

13.2.2 Sharing Data in Installed Common Areas

Sharing the same data among two or more processes can be done using installed common areas.

Typically, you use an installed common area for interprocess communication or for two or more processes to access the same data simultaneously.

13.2.2.1 Creating and Installing the Shareable Image Common Area

To communicate between processes using a common area, first install the common area as a shareable image:

1. Create the common area: Write an HP Fortran program that declares the variables in the common area and defines the common area. This program should not contain executable code. For example:

   COMMON /WORK_AREA/ WORK_ARRAY(8192) END

   
   This common area can use the BLOCK DATA statement.
   When compiling the source file that contains the common block declarations, consistently use the /ALIGNMENT and /GRANULARITY qualifiers (see Section 13.2.2.3). For example:

   $ FORTRAN/ALIGN=COMMONS=NATURAL/GRANULARITY=LONGWORD INC_COMMON.F90

2. Make the common area a shareable image: Compile the program containing the common area and use the LINK/SHAREABLE command to create a shareable image containing the common area. You need to specify a linker options file (shown here as SYS$INPUT to allow typed input) to specify the PSECT attributes of the COMMON block PSECT and include it in the global symbol table:

   $ LINK/SHAREABLE INC_COMMON ,SYS$INPUT/OPTION SYMBOL_VECTOR=(WORK_AREA=PSECT) PSECT_ATTR=WORK_AREA,SHR [Ctrl/Z]

   
   With HP Fortran on OpenVMS Alpha systems, the default PSECT attribute for a common block is NOSHR (see Section 13.1). To use a shared installed common block, you must specify one of the following:
   • The SHR attribute in a cDEC$ PSECT directive in the source file
   • The SHR attribute in the linker options file for the shareable image to be installed and for each executable image that references the installed common block
   
   If the !DEC$ PSECT (same as cDEC$ PSECT) directive specified the SHR attribute, the LINK command is as follows:

   $ LINK/SHAREABLE INC_COMMON ,SYS$INPUT/OPTION SYMBOL_VECTOR=(WORK_AREA=PSECT) [Ctrl/Z]

   
   The source line containing the !DEC$ PSECT directive is as follows:

   !DEC$ PSECT /INC_COMMON/ SHR

3. Copy the shareable image: Once created, you should copy the shareable image into SYS$SHARE: before it is installed. The file protection of the .EXE file must allow write access for the processes running programs that will access the shareable image (shown for Group access in the following COPY command):

   $ COPY/LOG DISK$:[INCOME.DEV]INC_COMMON.EXE SYS$SHARE:*.*/PROTECTION=G:RWE

   
   If you do not copy the installed shareable image to SYS$SHARE, before running executable images that reference the installed shareable common image, you must define a logical name that specifies the location of that image.
4. Install the shareable image: Using an account with CMKRNL privilege, invoke the interactive Install Utility. When the INSTALL> prompt appears, type a line containing the following:
   1. The CREATE (or ADD) command
   2. The complete file specification of the shareable image that contains the common area (file type defaults to EXE)
   3. The qualifiers /WRITABLE and /SHARED
   
   The Install utility installs your shareable image and reissues the INSTALL> prompt. Type EXIT to exit. For example:

   $ INSTALL INSTALL> CREATE SYS$SHARE:INC_COMMON/WRITABLE/SHARED INSTALL> EXIT $

   
   A disk containing an installed image cannot be dismounted until you invoke the Install Utility and type DELETE, followed by the complete file specification of the image.

For More Information:

• On default PSECT attributes, see Section 13.1.
• On the !DEC$ PSECT (cDEC$ PSECT) compiler directive statement, see the HP Fortran for OpenVMS Language Reference Manual.
• On the Install Utility, see the VMS Install Utility Manual.
• On synchronizing access to a common block installed as a shareable image, see Section 13.2.2.3.
• On the linker, see Chapter 3 and the HP OpenVMS Linker Utility Manual.
• On sharing common block data using a global section, see Section F.4 and the HP OpenVMS Programming Concepts Manual.
• On page size differences between OpenVMS VAX and OpenVMS Alpha systems, see Migrating an Application from OpenVMS VAX to OpenVMS Alpha.

After the common area has been installed as a shareable image, use the following steps to access the data from any executable program:

1. Include the same variable declarations and common area declarations in the accessing program or programs.
   All common block data declarations must be compatible wherever the common block is referenced.
2. Compile the program.
   When compiling the program that contains the common block declarations, consistently use the same /ALIGNMENT and /GRANULARITY qualifiers used to compile the common block data declaration program that has been installed as a shareable image (see Section 13.2.2.3).
   For example, assume the two programs named INCOME and REPORT that will access a common block WORK_AREA in the installed shareable image INC_COMMON:

   $ FORTRAN/ALIGN=COMMONS=NATURAL/GRANULARITY=LONGWORD INCOME.F90 $ FORTRAN/ALIGN=COMMONS=NATURAL/GRANULARITY=LONGWORD REPORT.F90

3. Link the accessing program against the installed common area program.
   You must use an options file to specify the common area program as a shareable image.
   The following are LINK commands:

   $ LINK INCOME, INCOME/OPTION $ LINK REPORT, INCOME/OPTION

   
   The linker options file INCOME.OPT contains the following lines:

   INC_COMMON/SHAREABLE PSECT_ATTR=WORK_AREA, SHR

   
   If a !DEC$ PSECT (cDEC$ PSECT) directive specified the SHR PSECT attribute, the linker options file INCOME.OPT would contain the following line:

   INC_COMMON/SHAREABLE

   
   The source line containing the !DEC$ PSECT directive would be as follows:

   !DEC$ PSECT /INC_COMMON/ SHR

   
   For each executable image that references the installed shareable image containing the shared common area, you must specify the SHR PSECT attribute by using either of these:
   • !DEC$ PSECT (cDEC$ PSECT) directive
   • Linker options file
   
   The two programs access the same area of memory through the installed common block (program section name) WORK_AREA in the installed shareable image INC_COMMON.
4. If the installed image is not located in SYS$SHARE, you must define a logical name that specifies the location of that image. The logical name (in this example INC_COMMON) is the name of the installed image.
5. Execute the accessing program.
   In the previous series of examples, the two programs INCOME and REPORT access the same area of memory through the installed common block WORK_AREA in the installed shareable image INC_COMMON.

For More Information:

• On the /ALIGNMENT qualifier, see Section 2.3.3.
• On the /GRANULARITY qualifier, see Section 2.3.23.
• On intrinsic data types, see Chapter 8.
• On the Alpha architecture, see the Alpha Architecture Reference Manual.
• On the Itanium architecture, see the Intel Itanium Architecture Software Developer's Manual, Volume 1: Application Architecture.