HP OpenVMS Systems

DEC Ada predefines the following input-output packages on all platforms:

• DIRECT_IO
• DIRECT_MIXED_IO
• SEQUENTIAL_IO
• SEQUENTIAL_MIXED_IO
• TEXT_IO
• IO_EXCEPTIONS

The packages DIRECT_IO, SEQUENTIAL_IO, TEXT_IO, and IO_EXCEPTIONS are predefined by the Ada language. The remaining packages are predefined by the DEC Ada implementation.

The packages SEQUENTIAL_MIXED_IO and DIRECT_MIXED_IO are analogous to their "non-mixed" counterparts, but they allow each external file record to contain multiple values of various types. These packages allow for a convenient interchange of data using files created or used by other DIGITAL languages, such as DIGITAL Fortran and DEC C.

DEC Ada predefines the following input-output packages on OpenVMS systems only:

• INDEXED_IO
• INDEXED_MIXED_IO
• RELATIVE_IO
• RELATIVE_MIXED_IO
• AUX_IO_EXCEPTIONS

The package RELATIVE_IO is similar to the package DIRECT_IO but adds the ability to detect empty records (as in COBOL). The package INDEXED_IO is also similar and adds the ability to locate records by key value. Like the packages SEQUENTIAL_IO and DIRECT_IO, both RELATIVE_IO and INDEXED_IO are instantiated with a type to create a package for external files whose elements are all of that same type.

The package AUX_IO_EXCEPTIONS defines the additional exceptions needed by the relative and indexed input-output packages.

As a convenience, instantiations of the generic packages INTEGER_IO and FLOAT_IO (from the package TEXT_IO) are provided for some of the predefined integer and floating-point types defined in the package STANDARD. For example, the package INTEGER_TEXT_IO is an instantiation of INTEGER_IO for the type INTEGER.

DEC Ada provides a package LOW_LEVEL_IO, not for general use but for the implementation of the other input-output packages.

On OpenVMS systems, DEC Ada allows the direct invoking of OpenVMS input-output services and Record Management Services (RMS). However, for most applications, it is not necessary to do so. The DEC Ada predefined input-output packages provide a rich and comprehensive set of file operations and each input-output package is tailored for operations on a specific kind of file.

On OpenVMS systems, familiarity with the following is recommended:

• RMS file organizations and access methods
• OpenVMS file specifications and directories
• OpenVMS File Definition Language (FDL)

On DIGITAL UNIX systems, DEC Ada predefined packages and their operations are implemented using DIGITAL UNIX system calls and input-output facilities.

On DIGITAL UNIX systems, familiarity with the following is recommended:

• DIGITAL UNIX files
• DIGITAL UNIX input-output facilities

On all platforms, the attributes of the external file, the storage medium, and the input-output package determine which operations can be used to manipulate data.

On OpenVMS systems, DEC Ada permits the sharing of external files, which enables concurrent access to the same external file and can take place in the same OpenVMS process or across multiple processes. File sharing permits multiple file objects to be associated with the same external file. Files can be shared for reading, writing, or modifying.

In addition, DEC Ada uses the RMS automatic locking facility to provide record-locking capabilities. This means that when an external file is opened in more than one place, the operations are automatically coordinated. Record locking ensures that one task cannot add, delete, or modify a record of an external file that is concurrently being accessed by another task. Record locking also coordinates accesses between programs that are executing as separate OpenVMS processes. This includes processes executing on different nodes of an OpenVMS Cluster (including mixed-architecture OpenVMS Clusters) or DECnet network.

On DIGITAL UNIX systems, DEC Ada has no special sharing or locking capabilities. External files can be shared or locked at the operating-system level, using DIGITAL UNIX system calls.

5.1 File Elements

In DEC Ada, input-output operations for all nontext files are defined in terms of file elements. Values retrieved for an element of a file object are read from an element of the external file. Values transferred to an element of a file object are written to an element of the external file. On OpenVMS systems, each DEC Ada external file element corresponds to an RMS record.

For files containing values of mixed types, an element can represent a single value (just as an element in a file of uniform-type values represents a single value) or it can represent a set of values or items. A mixed-type file, then, can be a file of elements of different types or it can be a file of elements whose items have different types. DEC Ada provides an additional set of input-output operations, defined in terms of items, for mixed-type files.

Input-output operations for text files are not defined in terms of elements. Rather, they are defined in terms of lines and in terms of values or items of various types.

5.2 The FORM Parameter in DEC Ada

All of the DEC Ada input-output packages provide CREATE and OPEN procedures that have a FORM parameter, which corresponds to the language-required form string. The FORM parameter determines the system-dependent characteristics or attributes associated with an external file when it is opened or created.

5.2.1 The FORM Parameter on OpenVMS Systems

On OpenVMS systems, the value of the FORM parameter can be one of the following:

• A string of statements of the OpenVMS Record Management Services (RMS) File Definition Language (FDL)
• A string referring to a text file of FDL statements (called an FDL file)

On OpenVMS systems, each input-output package has a default string of FDL statements that is used to open or create a file. In general, specification of a FORM parameter is not necessary. It is never necessary in an OPEN procedure although it may be necessary in a CREATE procedure.

Any explicit FORM specification supersedes the default attributes of the governing input-output package.

On OpenVMS systems, a name can be specified in FORM. However, NAME overrides any name given in FORM. If NAME is null, any name given in FORM is ignored and a temporary file is created that is not accessible after the file is closed.

5.2.2 The FORM Parameter on DIGITAL UNIX Systems

On DIGITAL UNIX systems, the value of the FORM parameter conforms to the description of the FORM parameter in IEEE Standard 1003.5-1992, IEEE Standard for Information Technology, POSIX Ada Language Interfaces.

Each input-output package has an implementation-defined value form string that is used to open or create a file. In general, specification of a FORM parameter is not necessary.

On DIGITAL UNIX systems, a file descriptor can be specified in FORM. If the external file referred to by the file descriptor is already open, then the Ada file is opened and the file pointer is set to the beginning of the file.

5.2.3 The FORM Parameter on ULTRIX Systems

On ULTRIX systems, the value of the FORM parameter must be a character string.

Depending on the fields specified, the value of the FORM parameter may represent one or more of the following:

• The size of the buffer used during file operations. The field value specifies the number of bytes in the buffer.
• The maximum element size for a direct file. The field value specifies the maximum number of bytes in the element.
• A file descriptor for the Ada file being opened. The file descriptor must be open.
  If the file descriptor is not open or if it refers to an Ada file that is already open, then the exception USE_ERROR is raised. The file descriptor option can be used only in the FORM parameter of an OPEN procedure.

Each input-output package has an implementation-defined value form string that is used to open or create a file. In general, specification of a FORM parameter is not necessary.

Many other file service facilities are also available. DEC Ada supports asynchronous input-output on all systems.

Execution of input-output for access types (including types that have components of an access type) is erroneous.

5.3 Relative and Indexed Files (OpenVMS Only)

On OpenVMS systems, DEC Ada defines relative access and indexed access in addition to sequential and direct access. The corresponding file types and the associated operations are provided by the predefined generic packages RELATIVE_IO and INDEXED_IO. A file object to be used for relative access is called a relative file. A file object to be used for indexed access is called an indexed file.

Relative and indexed access are also provided in the predefined (nongeneric) packages RELATIVE_MIXED_IO and INDEXED_MIXED_IO, which allow values of different types to be mixed in a file.

For relative access, the file is viewed as a set of fixed-length cells occupying consecutive positions in linear order. Cells can either be empty or can contain fixed- or variable-length elements.

For indexed access, the file is viewed as a set of elements that are ordered by predefined keys. Each key has a number (a nonnegative integer) and a value.

5.4 Mixed-Type Input-Output

The following DEC Ada predefined packages provide types and operations for files consisting of elements that can contain zero or more items of various types:

• SEQUENTIAL_MIXED_IO
• DIRECT_MIXED_IO
• RELATIVE_MIXED_IO
• INDEXED_MIXED_IO

The packages RELATIVE_MIXED_IO and INDEXED_MIXED_IO are available on OpenVMS systems only.

Each file opened by one of these mixed-type input-output packages has an associated file buffer maintained by the package. The size of the file buffer is limited by the maximum element size of the external file. The maximum element size is controlled by the FORM parameter in a CREATE or OPEN procedure as follows:

• On OpenVMS systems, the maximum element size is controlled by a FORM parameter that includes the string "RECORD; SIZE max_record_size".
• On DIGITAL UNIX systems, the maximum element size is controlled by a FORM parameter that includes the string "ELEMENT_SIZE => max_element_size".

On OpenVMS systems, element (RMS record) locking is provided for the packages RELATIVE_MIXED_IO and INDEXED_MIXED_IO.

5.5 Text Input-Output

DEC Ada provides the package TEXT_IO for creating and working with text files. TEXT_IO is not generic, but it does include generic packages for files. It also includes generic packages for the input and output of integers, floating-point numbers, fixed-point numbers, and enumeration values.

To make the use of the generic TEXT_IO operations more convenient, DEC Ada provides predefined library packages that instantiate the integer and floating-point operations for the predefined integer and floating-point types as shown in Table 5-1.

On OpenVMS systems, DEC Ada has two logical file names, ADA$INPUT and ADA$OUTPUT, which can be defined to refer to the standard input and standard output files. If these logical names are not defined, then the standard input and standard output files are represented by the default system input and output logical names SYS$INPUT and SYS$OUTPUT.

On DIGITAL UNIX systems, the DEC Ada standard input file corresponds to the DIGITAL UNIX file descriptor 0; the standard output file corresponds to the DIGITAL UNIX file descriptor 1.

5.6 Input-Output in Tasking Programs

Ada input-output in tasking programs is asynchronous. All of the DEC Ada input-output packages are integrated with the multitasking support in the run-time library so that operations on an internal file are indivisible (atomic) in the presence of concurrent calls from multiple tasks. In addition, input-output operations invoked from a task suspend the execution of only that task until they are completed. Other tasks can continue to execute while the task executing the input-output is waiting.

Because there is no automatic file locking in DIGITAL UNIX, unpredictable results can occur when a file is opened several times concurrently. The flock(2) system call can be used to synchronize access to a file to avoid problems caused by concurrent access to the file.

5.7 Exceptions in Input-Output

In DEC Ada, the exception DEVICE_ERROR is never raised. Device-related errors raise the exception USE_ERROR.

A library of predefined units is supplied as part of the DEC Ada implementation. Included in this library are predefined units as described in the Ada standard (such as the predefined package TEXT_IO), as well as additional units.

The complete specifications and, in some cases, the bodies for these units can be obtained from the directory of predefined units.

On OpenVMS systems, when a new program library is created, all the units from the predefined library are automatically entered into the newly created library. The predefined library is identified using the logical name ADA$PREDEFINED, which is established as a system logical name as part of the DEC Ada installation procedure.

On DIGITAL UNIX systems, when a new DEC Ada program library is created, a default program library context that includes all the units from the predefined library is associated with the newly created library. The predefined library is identified in the default context as /usr/lib/adalib .

On DIGITAL UNIX systems, the default DEC Ada predefined library is compiled with IEEE_FLOAT. VAX_FLOAT is not available.

On all systems, groups, projects, and individuals can specify that an alternative library containing predefined units be used. (For example, an alternative library might contain additional units specific to an installation or project.)

The default DEC Ada predefined library, on both OpenVMS VAX and OpenVMS Alpha, is compiled with VAX_FLOAT. Users get errors when compiling with IEEE_FLOAT because floating-point formats do not match. On VAX, VAX_FLOAT is the only format. Users on Alpha no longer need to recompile the predefined library to change the VAX_FLOAT default, because DEC Ada for OpenVMS Alpha now provides another predefined library compiled with the IEEE floating-point format. As part of the installation procedure, you are asked if you want to install an IEEE floating-point predefined library. The default is "no," but if you wish to install an IEEE floating-point library, simply type "y" at this point.

Packages LIB and MTH were changed to convert correctly between FLOAT and F-floating types.

On OpenVMS systems, the package STANDARD is named $STANDARD; on DIGITAL UNIX systems, it is named _STANDARD.

6.1 Standard Units

The following units defined in the Ada standard are included in the predefined library:

• Package CALENDAR
• Package DIRECT_IO
• Package IO_EXCEPTIONS
• Package SEQUENTIAL_IO
• Package STANDARD
  The predefined types are declared in the package STANDARD.
• Package SYSTEM
  DEC Ada provides a system-specific versions of the package SYSTEM. For more information, see the Section "Package SYSTEM Platform Differences."
• Package TEXT_IO
• Generic function UNCHECKED_CONVERSION
  UNCHECKED_CONVERSION is supported, subject to the following rules:
  • The actual subtype corresponding to the formal type TARGET must not be an unconstrained array type or an unconstrained type with discriminants.
  • When the target type is a type with discriminants, the value resulting from a call of the conversion function resulting from an instantiation of the generic function UNCHECKED_CONVERSION is checked to ensure that the discriminants satisfy the constraints of the actual subtype.
  • For an unchecked conversion, when the size of the source value is not the same as the target subtype, the value is truncated (high-order bits ignored) or zero-filled (high-order bits are zeros).
• The generic procedure UNCHECKED_DEALLOCATION

The predefined types are the types that are declared in the predefined package STANDARD. This package also includes the declarations of their predefined operations. For more information, see Chapter 2.

Apart from the predefined numeric types, the specification of the package STANDARD must be the same for all implementations of the language.

The package MACHINE_CODE is not provided. (Machine code insertions are not supported.)

Package SYSTEM Platform Differences

The following lists differences in the package SYSTEM:

• OpenVMS systems use 32-bit addresses. DIGITAL UNIX systems use 64-bit addresses.
• Function TO_ADDRESS(X:AST_HANDLER) is supported on OpenVMS systems only.
• DEC Ada provides:
  • Type ADDRESS
  • Operators "+" and "-" for use with the types ADDRESS and INTEGER
  • Conversions between the types ADDRESS and INTEGER
  
  These operators are also available on DIGITAL UNIX systems. However, because the type INTEGER is 32-bits and the type ADDRESS is 64-bits, DIGITAL recommends using the package ADDRESS_OPERATIONS.
• On DIGITAL UNIX systems, a second overloading of SET_INTERLOCKED and CLEAR_INTERLOCKED is defined. Also, on DIGITAL UNIX systems, the following are included for the types ALIGNED_INTEGER and ALIGNED_LONG_INTEGER:
  • ADD_ATOMIC
  • OR_ATOMIC
  • AND_ATOMIC
• The following procedures correspond to the instructions and are provided on OpenVMS systems only:
  • INSQHI
  • REMQHI
  • INSQTI
  • REMQTI
• The types INSQ_STATUS and REMQ_STATUS correspond to the instructions and are provided on OpenVMS systems only. They are enumeration types and correspond to different enumeration literals on the two targets.

This section is divided into the following areas:

• Packages common to all platforms
• Packages available on OpenVMS systems only
• Packages available on DIGITAL UNIX systems only

The following packages are available on all DIGITAL platforms:

• ADDRESS_OPERATIONS
  Provides generic address and integer operations to supplement similar operations in the package SYSTEM.
• ASSERT, ASSERT_EXCEPTIONS, ASSERT_GENERIC
  Provide types, operations, and exceptions to allow users to insert and enable code-checking assertions in their Ada source code.
• C_TYPES
  Collects Ada type definitions and conversion operations that correspond to familiar types defined by the C language.
• CURRENT_EXCEPTION
  Provides information about specific exceptions as they arise.
• ELEMENTARY_FUNCTIONS_EXCEPTIONS
  Collects predefined exceptions used in the packages GENERIC_ELEMENTARY_FUNCTIONS and GENERIC_PRIMITIVE_FUNCTIONS.
• GENERIC_ELEMENTARY_FUNCTIONS
  An ISO standard package that contains SQRT, LOG, EXP, and standard trigonometric functions.
• GENERIC_PRIMITIVE_FUNCTIONS
  An ISO standard package that contains various utility functions, including FLOOR, CEILING, and functions that return the exponent and fraction of a floating-point value.
• GET_TASK_INFO
  Provides information about specific Ada tasks.
• MATH_LIB
  Provides a set of mathematical operations.
  As a convenience, instantiations of the package MATH_LIB are provided for each of the predefined floating-point types defined in the predefined package STANDARD. For example, FLOAT_MATH_LIB is an instantiation of MATH_LIB for the type FLOAT.
• SYNCHRONIZE_NONREENTRANT_ACCESS
  Provides a locking protocol that will prevent problems when calling routines that are not fully reentrant.

Packages are provided in the predefined library to help users who want to migrate from Ada 83 to Ada 95. DEC Ada has replaced the Ada 95 dots (.), which signify child units, with underscore (_) characters, as shown in the following table:

The following packages are available on OpenVMS VAX and Alpha systems only:

• AUX_IO_EXCEPTIONS
  Defines the exceptions needed by the relative and indexed input-output packages.
• CDD_TYPES
  Provides types for the translation of common data dictionary types into Ada types.
• CLI, NCS, LBR, SOR
  Provide types and operations for calling OpenVMS command language interpreter, National Character Set, Librarian utility, and Sort/Merge utility routines.
• CONDITION_HANDLING
  Provides types and operations for accessing the OpenVMS exception-handling mechanism.
• CONTROL_C_INTERCEPTION
  Eases invocation of the OpenVMS Debugger in certain tasking programs.
• DTK, LIB, MTH, OTS, PPL, SMG, STR
  Provide types and operations for calling OpenVMS Run-Time Library routines.
• RMS_ASYNCH_OPERATIONS
  Used in the implementation of TASKING_SERVICES.
• STARLET
  Provides types and operations for direct use of OpenVMS and OpenVMS Record Management Services (RMS) system services.
• SYSTEM_RUNTIME_TUNING
  Provides operations for changing system parameters that are normally controlled by the run-time library.
• TASKING_SERVICES
  Provides task-synchronous and process-asynchronous alternatives to those OpenVMS system services and OpenVMS RMS routines that typically suspend a complete program (not just a single task) in the absence of special handling.
  The subprograms in this package make it unnecessary to resort to asynchronous system traps (ASTs) to achieve task-synchronous and process-asynchronous behavior.

The following packages are available on DIGITAL UNIX systems only:

• ERRNO
  Provides Ada definitions for the values defined in <errno.h>. Also provides subprograms for ensuring that tasks can obtain the value of errno expected.
• MAIN_PROGRAM_ARGUMENT_LIST
  Gives access to arguments that are passed to a process at execution time.
• SET_TASK_PRIORITY
  Provides types and operations for changing task priorities and giving Ada tasks DIGITAL UNIX real-time and system priorities.
• TIME_CONVERSION
  Provides types and functions for converting time values.

The package SIGNAL_WAITING is available on ULTRIX systems only. It provides types and operations for handling ULTRIX signals from Ada tasks.

6.3 DEC Ada Predefined Instantiations

For convenience and for the purpose of saving compilation time and object code space, DEC Ada predefines the instantiations of some commonly used generic packages. See Table 6-1.