# Compaq COBOL
User Manual

Previous | Contents | Index

# Chapter 16
Managing Memory and Data Access

Compaq COBOL provides compile-time mechanisms you can select to control run-time memory access. Effective memory management can improve:

- Compile-time performance
- Run-time performance
- Compatibility
- System resource usage

You place compiler command-line qualifiers and flags, and/or embedded directives in your source code to alter data alignment and to structure memory references. All such directives begin with the characters *DC, where the asterisk (*) signals the beginning of the structured comment to the compiler. You use these alignment directives exclusively in the Data Division. (If you compile this code on Compaq COBOL for OpenVMS VAX, a structured comment *DC directive is treated like any other comment and ignored.)

This chapter provides the following information about managing memory and data access:

- Managing memory granularity (Alpha) ( Section 16.1)
- Using the VOLATILE compiler directive (Alpha) ( Section 16.2)
- Aligning data for performance and compatibility (Alpha) ( Section 16.3)
- Using alignment directives, qualifiers, and flags (Alpha) ( Section 16.4)

# 16.1 Managing Memory Granularity (Alpha)

You can control the Compaq COBOL compiler granularity to set the minimum size of a memory access. Granularity refers to the amount of storage that can be modified when updating a data item.

The form on Tru64 UNIX systems is:

    -granularity option  <>

The form on OpenVMS Alpha systems is:

    /GRANULARITY=option  <>

You can specify the following values for option:

- byte
- long
- quad (default)

To update a data byte, the Compaq COBOL compiler will issue a sequence of instructions to fetch the longword or quadword containing the byte, update the memory inside the longword or quadword, and then write the longword or quadword back to memory.

If different processes sharing memory try concurrently to update different parts of the same aligned quadword, this multi-instruction sequence can cause one of the updates to be lost. If you have multiple processes concurrently updating different bytes within the same aligned quadword, you should use byte granularity. Use longword granularity for better performance if you are sure the processes never make concurrent updates within the same aligned longword. Use quadword granularity for best performance if you are sure the processes never make concurrent updates within the same aligned quadword.

To successfully use byte/word granularity, you need to consider at least four important restrictions:

- An EV56 or higher CPU is necessary for byte/word granularity.
- LIBOTS.EXE support for byte/word granularity is necessary if PIC X support is needed. However, LIBOTS.EXE Version 1.3 on OpenVMS Alpha Version 7.1 does not support byte/word granularity.
- Use of PIC 9 COMP-3 (PACKED numerics) and PIC 9 (DISPLAY numerics) should be restricted, because they do not have byte/word granularity support.
- You need to evaluate any NONGRNACC diagnostics as potentional sources of incorrect data update. These warnings contain critical information and must not be ignored.

You should avoid the use of /GRANULARITY=BYTE unless all of these requirements are met.

In the following example (which is OpenVMS specific), the warnings at lines 16, 17, and 18 must be heeded. If this application is run on a CPU that supports byte/word granularity, the warning at line 16 (PIC X) indicates that the move will not produce byte granularity unless it is run on a system with a LIBOTS.EXE version that supports byte/word granularity. The warnings at line 17 (PIC 9 display numeric) and line 18 (PIC 9 COMP-3 packed numeric) indicate that these moves will not produce byte granularity.

    $ cobol c3484/granularity=byte/list=sys$output
    C3484   Source Listing   5-JUN-1999 07:37:22  Compaq COBOL V2.6-1060  Page 1

           1 identification division.
           2 program-id. c3484.
           3 environment division.
           4 data division.
           5 working-storage section.
           6 01 w1.
           7 03   a1   pic 9(9) comp.
           8 03   a2   pic 9(4) comp.
           9 03   a3   pic x(9).
          10 03   a4   pic 9(9).
          11 03   w2 occurs 3 times.
          12 05     a5 pic 9(18) comp-3.
          13 procedure division.
          14 0. move 1   to a1.
          15  move 2   to a2.
          16  move "c" to a3.
      ........1
    %COBOL-W-NONGRNACC, (1) Unable to generate code for requested granularity

          17  move 4   to a4.
      ........1
    %COBOL-W-NONGRNACC, (1) Unable to generate code for requested granularity

          18  move 5   to a5(2).
      ........1
    %COBOL-W-NONGRNACC, (1) Unable to generate code for requested granularity

          19  if a1      not = 1   display "?1".
          20  if a2      not = 2   display "?2".
          21  if a3(1:1) not = "c" display "?3 ".
          22  if a4      not = 4   display "?4".
          23  if a5(2)   not = 5   display "?5".
          24  stop run.

# 16.2 Using the VOLATILE Compiler Directive (Alpha)

VOLATILE directives offer flexibility and selectivity: they alter the current storage of certain data items by specifying new storage information from within the program source.

The SET VOLATILE directive enables you to direct that certain data items be stored in memory, rather than in machine registers. This technique is useful for declaring data that is to be accessed asynchronously. (Device driver applications often use volatile data storage.)

The forms of the VOLATILE directives are as follows:

        *DC SET VOLATILE
        *DC SET NOVOLATILE
        *DC END-SET VOLATILE

In your application you specify *DC SET VOLATILE to begin a range of data declarations with this attribute set. You terminate the volatile attribute range with the *DC END-SET VOLATILE (or *DC SET NOVOLATILE) directive. Subsequent declarations will not be affected.

# 16.3 Aligning Data for Performance and Compatibility (Alpha)

Proper alignment is important for Compaq COBOL applications on both Tru64 UNIX and OpenVMS Alpha platforms. Manipulation of binary data (that is, COMP, COMP-1, COMP-2, INDEX, and POINTER data items) is significantly faster if alignment is on natural boundaries. A natural boundary is the smallest boundary at which data can be aligned without crossing the next boundary for that type. (For example, longword is the natural boundary for four-byte integers.)

Two forms of alignment are available in Compaq COBOL. The basic form of alignment allows you to align only elementary data items without padding the record structures and substructures within which they reside. The alternate form, which is Alpha alignment and padding, aligns both the elementary data items and the structures and substructures in which they are found. It also pads out those structures and substructures to lengths which are multiples of their alignments. This form of alignment and padding conforms to the Compaq Alpha Calling Standards.

OpenVMS VAX compatible record layouts are available for compatibility with applications running on OpenVMS VAX platforms, including Compaq COBOL for OpenVMS VAX.

## 16.3.1 Data Boundaries (Alpha)

Natural alignment for binary data is detailed in Table 16-1. The boundaries described in Table 16-1 are specified in the Compaq Alpha Calling Standards. The table generally applies both to Tru64 UNIX and to OpenVMS Alpha, with the exception that IEEE is the only floating point data type on the Tru64 UNIX operating system.

Table 16-1 Boundaries for Naturally Aligned Binary Data (Alpha)
COBOL USAGE | PICTURE Declaration | OpenVMS Alpha Standard Data Type | Natural Alignment | Allocated Storage
--- | --- | --- | --- | ---
DISPLAY | PIC A PIC X PIC 9 PIC EDITED | 8-bit character string | BYTE | 1 byte
COMP | PIC [S]9(1-4) | 16-bit word integer | WORD | 2 bytes
| PIC [S]9(5-9) | 32-bit longword integer | LONGWORD | 4 bytes
| PIC [S]9(10-18) | 64-bit quadword integer | QUADWORD | 8 bytes
| PIC [S]9(19-31) | 128-bit octaword integer | QUADWORD | 16 bytes
COMP-1 | Not applicable | 32-bit F-floating | LONGWORD | 4 bytes
|  | 32-bit IEEE S-floating | LONGWORD | 4 bytes
COMP-2 | Not applicable | 64-bit D-floating | QUADWORD | 8 bytes
|  | 64-bit G-floating | QUADWORD | 8 bytes
|  | 64-bit IEEE T-floating | QUADWORD | 8 bytes
INDEX | Not applicable | 32-bit longword integer | LONGWORD | 4 bytes 1
POINTER | Not applicable | 32-bit longword integer | LONGWORD | 4 bytes 2

1 On the OpenVMS Alpha system, USAGE IS INDEX is allocated as a longword integer for OpenVMS VAX compatibility. On the Tru64 UNIX system, it is allocated as a 64-bit quadword integer, with 8 bytes of storage.
2 On the OpenVMS Alpha system, Compaq COBOL allocates 4 bytes for POINTER data to maintain Compaq COBOL for OpenVMS VAX compatibility. On the Tru64 UNIX system, it allocates 8 bytes for POINTER data (a 64-bit quadword integer).

## 16.3.2 Data Field Padding (Alpha)

In Compaq COBOL, all 01 and 77-level data items are always aligned on quadword boundaries. With Alpha natural alignment and padding invoked, the lengths of all data-items are compiled to be multiples of the greatest alignment of any subordinate elementary field.

The compiler will flag (with an Informational diagnostic) all fields that might incur side effects when compiled with alignment and padding enabled.

## 16.3.3 Alignment Directives, Qualifiers, and Flags (Alpha)

Within your program, you can specify alignment with the alignment directives, which consist of structured comments embedded within the DATA DIVISION of the program source.

When you compile a COBOL program, you can use the /ALIGNMENT qualifier or the /ALIGNMENT=PADDING qualifier on OpenVMS Alpha systems and `-align` or `-align pad` on Tru64 UNIX systems to specify aligned elementary data items or naturally aligned and padded record layouts for optimal performance. If you do not specify this option, the default alignment is used, which is OpenVMS VAX compatible record layouts for compatibility with Compaq COBOL for OpenVMS VAX and other OpenVMS VAX languages.

In addition to the primary goal of optimum performance, specifying data alignment offers the following advantages:

- Ease of use and conversion---You might need to make a minimal number of changes to existing source files before compiling them with the Compaq COBOL compiler. In some cases, all you need to do is specify the `-align` flag or the /ALIGNMENT qualifier with or without the padding option when you compile.
- Flexibility---You can specify VAX compatible alignment (byte alignment) or natural alignment on a record-by-record basis. For example, you can specify VAX compatible alignment for files shared by both compilers and natural alignment for Compaq COBOL-only files and records.

Note The two types of padding (use of alignment with the PADDING option, or use of *DC SET PADALIGN) are not recommended in a COBOL program that contains the REDEFINES or RENAMES syntax.

## 16.3.4 Specifying Alignment at Compile Time (Alpha)

The result of the alignment command-line option is identical on the OpenVMS Alpha and the Tru64 UNIX operating systems.

On OpenVMS Alpha systems, the /ALIGNMENT qualifier used with the COBOL command aligns data on Alpha natural boundaries and optionally pads data structures that contain them, in conformity with the Compaq Alpha Calling Standards. The format of the /ALIGNMENT qualifier is as follows:

    /ALIGNMENT[=[NO]PADDING] or /NOALIGNMENT   <>

On Tru64 UNIX systems, you use the `-align` flag with the `cobol` command to align elementary data items on Alpha natural boundaries and optionally to pad data structures which contain them, in conformity with the Compaq Alpha Calling Standards. The format of the `-align` flag is as follows:

`-align [padding] <>`

On all three patforms, the default is alignment on Alpha natural boundaries and no padding of interior or terminal fields (for 01-level data items and data structures).

The alignment command-line qualifier or flag specifies the minimum alignment for data items specified within the program source when no additional alignment information has been specified. You can specify the minimum alignment of specific data items within your program by including compiler directives in the program source.

The `-align` flag or the /ALIGNMENT qualifier aligns all COMP, COMP-1, COMP-2, INDEX, and POINTER data along natural boundaries. (See Table 16-1.)

By default, alignment is turned off and data is aligned on byte boundaries.

The alignment specified in the compile command is in force throughout a given compilation, except as modified by any compiler directives. In addition, the alignment of elementary binary data that has been specified with the SYNCHRONIZED clause is unchanged.

# 16.4 Using Alignment Directives, Qualifiers, and Flags (Alpha)

Alignment directives offer flexibility and selectivity: they alter the current alignment by specifying new alignment information from within the source program.

The forms of the alignment directives are as follows:

        *DC SET ALIGNMENT
        *DC SET NOALIGNMENT
        *DC END-SET ALIGNMENT

        *DC SET PADALIGN
        *DC SET NOPADALIGN
        *DC END-SET PADALIGN

The *DC SET ALIGNMENT directive and the *DC SET PADALIGN directive function independently of each other, except when their scopes overlap in the program source. In case of overlapping scope, the effect of the *DC SET PADALIGN directive prevails.

The *DC SET ALIGNMENT directive specifies natural Alpha alignment of elementary data items. The *DC SET PADALIGN specifies Alpha natural alignment and padding.

The *DC SET NOALIGNMENT directive specifies OpenVMS VAX compatible alignment.

The optional *DC END-SET ALIGNMENT directive terminates the current *DC SET ALIGNMENT or *DC SET NOALIGNMENT directive that is currently in effect.

The alignment of binary data that has been specified with the SYNCHRONIZED clause is unaffected by the *DC SET ALIGNMENT and *DC SET PADALIGN directives.

When you use an alignment directive or qualifier to align data in records, you should consider whether the data will be written to a file to be accessed by applications written in Compaq COBOL for OpenVMS VAX.

Note These directives are not allowed in the PROCEDURE DIVISION of a program source.

## 16.4.1 Order of Alignment Operations (Alpha)

Table 16-2 shows the order of precedence of the primary alignment qualifiers and directives in Compaq COBOL.

Table 16-2 Alignment and Padding Order of Precedence (Alpha)
| Compiler Directives
--- | ---
Command line Qualifier and Option | No Directive in Effect | *DC SET ALIGNMENT | *DC SET PADALIGN | *DC SET NOALIGN
(none) | None | Align elementary data items. | Align and pad elementary data items and structures. | None
/ALIGNMENT `-align` | Align elementary data items. | Align elementary data items. | Align and pad elementary data items and structures. | None
/ALIGN=PAD `-align pad` | Align and pad elementary data items and structures. | Align elementary data items and structures. | Align and pad elementary data items. | None

## 16.4.2 Nesting Alignment Directives (Alpha)

Alignment directives located within the source program alter the current alignment by specifying a new alignment, which remains in effect (except for data specified with SYNCHRONIZED, which remains unchanged) until changed precedence, or until the beginning of the next file specified in a comma list. You can nest alignment directives within a program to specify different alignments for selected sets of data. Alignment directives do the following:

- A SET ALIGNMENT (or SET NOALIGNMENT) directive. At this point in the program source the alignment specified by this directive becomes the current alignment.
- An END-SET ALIGNMENT directive. At this point, the immediately preceding SET ALIGNMENT (or SET NOALIGNMENT) directive is closed. The current alignment now becomes one of the following:
  - The alignment specified by the closest previous unclosed alignment directive
  - The alignment specified by the command-line option if no previous alignment directive exists
- The beginning of the next file specified in a comma list (on the Compaq COBOL command line). This event closes all of the preceding alignment directives. The alignment specified with the command-line option becomes the current alignment.

Example 16-1 shows an example of nested alignment directives in source code.

Example 16-1 Using*DC SET ALIGNMENT Directives

       .
       .                                 (1)
       .

            *DC SET ALIGNMENT            (2)

            01 comp-group.
                02 cg-x1   pic x.
                02 cg-c1   pic 9(1) comp.

            *DC SET NOALIGNMENT          (3)

            01 comp-group-2.
                02 cg-x2   pic x.
                02 cg-c2   pic 9(1) comp.

            *DC END-SET ALIGNMENT        (4)

            01 comp-group-3.
                02 cg-x3   pic x.
                02 cg-c3   pic 9(1) comp.

            *DC END-SET ALIGNMENT        (5)

            01 comp-group-4.
                02 cg-x4   pic x.
                02 cg-c4   pic 9(1) comp.

1. Initially, OpenVMS VAX compatible alignment is specified either by NOALIGNMENT or the absence of ALIGN on the compile command.
2. The SET ALIGNMENT directive specifies alignment along natural boundaries, superseding the initial OpenVMS VAX compatible alignment.
3. The SET NOALIGNMENT directive specifies VAX compatible alignment; data is now byte-aligned.
4. The END-SET ALIGNMENT directive terminates the alignment specified with the previous SET directive ((3) SET NOALIGNMENT). Alignment is once again along the natural boundaries as specified by (2), the SET ALIGNMENT directive.
5. This END-SET ALIGNMENT directive terminates the alignment specified with the original directive ((2) SET ALIGNMENT). Alignment is now OpenVMS VAX compatible as specified by the default command-line option. <>

Previous | Next | Contents | Index