|
|
|
|
|
 |
HP C
|
| Previous | Contents | Index |
HP C for OpenVMS systems provides a set of run-time library functions and macros to perform I/O. Some of these functions perform in the same manner as I/O functions found on C implementations running on UNIX systems. Other HP C functions take full advantage of the functionality of the OpenVMS file-handling system. You can also access the OpenVMS file-handling system from your HP C program without using the HP C Run-Time Library (RTL) functions. In any case, the system that ultimately accesses files on OpenVMS systems is OpenVMS Record Management Services (RMS).
This chapter introduces you to the following RMS topics:
The file-handling capabilities of HP C fall into two distinct categories:
This chapter briefly reviews the basic concepts and facilities of RMS and shows examples of their application in HP C programming. Because this is an overview, the chapter does not explain all RMS concepts and features. For language-independent information about RMS, see the following manuals in the OpenVMS documentation set:
RMS supports three types of file organization:
The following sections describe these types of file organization.
The organization of a file determines how a file is stored on the media and, consequently, the possible operations on records. You specify the file's organization when you create the file; it cannot be changed.
However, you can use the File Definition Language Editor (FDL) and the CONVERT utility to define the characteristics of a new file, and then fill the new file with the contents of the old file of a different format. For more information, see the OpenVMS Utility Routines Manual.
Sequential files have consecutive records. There are no empty records separating records that contain data. This organization allows the following operations on the file:
Sequential organization is the only kind permitted for magnetic tape files and other nondisk devices.
Relative files have records that occupy numbered, fixed-length cells. The records themselves need not have the same length. Cells can be empty or can contain records so the following operations are permitted:
Relative file organization is possible only on disk devices.
Indexed files have records that contain, in addition to data and carriage-control information, one or more keys. Keys can be character strings, packed decimal numbers, and 16-bit, 32-bit, or 64-bit signed or unsigned integers. Every record has at least one key, the primary key, whose value in each record cannot be changed. Optionally, each record can have one or more alternate keys, whose key values can be changed.
Unlike relative record numbers used in relative files, key values in indexed files are not necessarily unique. When you create a file, you can specify that a particular key have the same value in different records (these keys are called duplicate keys). Keys are defined for the entire file in terms of their position within a record and their length.
In addition to maintaining its records, RMS builds and maintains indexes for each of the defined keys. As records are written to the file, their key values are inserted in order of ascending value in the appropriate indexes. This organization allows the following operations:
Indexed organization is possible only on disk devices.
The record access modes are sequential, direct by key, and direct by record file address. The direct access modes are possible only with files that reside on disks.
Unlike a file's organization, the record access mode is not a permanent attribute of the file. During the processing of a file, you can switch from one access mode to any other permitted for that file organization. For example, indexed files are often processed by locating a record directly by key, and then using that key's index to sequentially read all the indexed records in ascending order of their key values; this method is sometimes called the indexed-sequential access method (ISAM).
Records in RMS files can have the following formats:
RMS provides a number of functions that create and manipulate files. These functions use RMS data structures to define the characteristics of a file and its records. The data structures are used as indirect arguments to the function call.
The RMS data structures are grouped into four main categories, as follows:
RMS uses these data structures to perform file and record operations. Table 2-1 lists some of the common functions.
All RMS functions are directly accessible from HP C programs. The syntax for any RMS function has the following form:
|
int sys$name(struct rms_structure *pointer); |
In this syntax, name is the name of the RMS function (such as OPEN or CREATE); rms_structure is the name of the structure being used by the function.
The file-processing functions require a pointer to a file access block as an argument; the record-processing functions require a pointer to a record access block as an argument. Since sys$create is a file-processing function, its syntax is as follows:
|
int sys$create(struct FAB *fab); |
These syntax descriptions do not show all the options available when you invoke an RMS function. For a complete description of the RMS calling sequence, see the OpenVMS Record Management Services Reference Manual.
Finally, all the RMS functions return an integer status value. The format of RMS status values follows the standard format described in Chapter 3. Since RMS functions return a 32-bit integer, you do not need to declare the type of an RMS function return before you use it.
The HP C Run-Time Library (RTL) supplies a number of header files that describe the RMS data structures and status codes. Table 2-2 describes these header files.
Most HP C programmers include the <rms.h> header file, which includes all the other header files.
These header files define all the data structures as structure tag names. However, they perform no allocation or initialization of the structures; these header files describe only a template for the structures. To use the structures, you must create storage for them and initialize all the structure members as required by RMS. Note that these include files are part of HP C for OpenVMS systems. RMS is part of the OpenVMS environment and may contain other included header files not described here.
To assist in the initialization process, the HP C RTL provides initialized RMS data structure variables. You can copy these variables to your uninitialized structure definitions with a structure assignment. You can choose to take the default values for each of the structure members, or you can tailor the contents of the structures to fit your requirements. In either case, you must use the structure types to allocate storage for the structure and to define the members of the structure.
The initialized variables supply the RMS default values for each member in the structure; they specify none of the optional parameters. To determine what default values are supplied by the initialized variables, see the OpenVMS Record Management Services Reference Manual.
Table 2-3 lists the initialized RMS data structure variables and the structures that they initialize.
The declarations of these structures are contained in the appropriate header file.
The names of the structure members conform to the following RMS naming convention:
|
typ$s_fld |
The identifier typ is the abbreviation for the structure, the letter s is the size of the member (such as l for longword or b for byte), and the identifier fld is the member name, such as sts for the completion status code. The dollar sign ($) is a character used in OpenVMS system logical names. See the OpenVMS Record Management Services Reference Manual for a description of the members in each structure.
The file access block defines the attributes of the file. To initialize a file access block, assign the values in the initialized data structure cc$rms_fab to the address of the file access block defined in your program. Consider the following example:
/* This example shows how to initialize a file access block. */
#include <rms.h> /* Declare all RMS data structs */
struct FAB fblock; /* Define a file access block */
main()
{
fblock = cc$rms_fab; /* Initialize the structure */
.
.
.
}
|
Any of these RMS structures may be dynamically allocated. For example, another way to allocate a file access block is as follows:
/* This program shows how to dynamically allocate RMS structures. */
#include <rms.h> /* Declare all RMS data structs */
main()
{
/* Allocate dynamic storage */
struct FAB *fptr = malloc(sizeof (struct FAB));
*fptr = cc$rms_fab; /* Initialize the structure */
.
.
.
}
|
To change the default values supplied by a data structure variable, you must reinitialize the members of the structure individually. You initialize a member by giving the offset of the member and assigning a value to it. Consider the following example:
fblock.fab$l_xab = &primary_key; |
This statement assigns the address of the extended attribute block named primary_key to the fab$l_xab member of the file access block named fblock .
| Previous | Next | Contents | Index |
|
|||||||||||
