HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

Table RMS-9 and Table RMS-10 list the NAML block fields used as input and output for the Create service.

Creating Files with the Create-If Option

Note that setting the create-if (FAB$V_CIF) option in the FAB$L_FOP field specifies that if a new file has the same file specification as an existing file, RMS opens the existing file and no new file is created. Some fields in the FAB, such as the file organization (FAB$B_ORG) and record format (FAB$B_RFM) fields, are input to a Create service, but are output from an Open service. For example, the indexed file organization could be specified in the FAB$B_ORG field on a create-if operation. However, if an existing sequential file has the same file specification as the indexed file that the user is attempting to create, then the existing file is opened and the FAB$B_ORG field is set to sequential.

Creating Indexed Files

An indexed file consists of a prolog, with which it begins, and one or more index structures. RMS supplies the prolog with certain information about the file, including file attributes.

RMS supports two prolog levels, called Prolog 2 and Prolog 3. Unlike Prolog 2 files, Prolog 3 files allow for file compression and additional key types. For compatibility with RMS-11 data files that are transported or copied (without conversion) between systems, you may want to choose Prolog 2.

If you want to create a Prolog 3 file, you must be sure that records in the file are not larger than 32,224 bytes and, if the primary key is segmented, that the segments of the primary key do not overlap (one or more bytes of the record are used in more than one segment). If the primary key contains overlapping segments, you can consider using that key as an alternate key instead of a primary key or you can either request, or let RMS assign you, a Prolog 2 indexed file.

Prolog 3 is the default prolog for RMS, although RMS creates a Prolog 2 file only if the key characteristics are not compatible with Prolog 3 files. You can, however, override this default by requesting a specific prolog version. The option you choose in requesting a specific prolog level affects the behavior of RMS with regard to creating the file and returning error messages.

If you explicitly request a prolog version using the XABKEY XAB$B_PROLOG field in an application program, and if other file characteristics are incompatible with that prolog, then RMS returns an error message and does not attempt to create the file. For example, if you explicitly specify Prolog 2 in the XAB$B_PROLOG field and have requested a key type that is available only with Prolog 3 (such as an 8-byte integer key type), an error is returned and the file is not created.

However, if a specific prolog version is not explicitly requested in the XAB$B_PROLOG field, RMS selects the greatest prolog level that can support the specified key characteristics and does not return an error completion code.

In summary, there are two ways in which you can specify a particular prolog version:

• Specify the XAB$B_PROLOG field in a XABKEY block in an application program, affecting only the file being created.
• Use the DCL command SET RMS_DEFAULT/PROLOG to change the process default.

If you do not specify the XAB$B_PROLOG field in your application program, RMS examines your process defaults to check for prolog information. If this information is not specified in your process defaults, RMS examines the system defaults. If no prolog information is specified at the system level, RMS attempts to create a Prolog 3 file.

You need not be concerned with the distinctions between Prolog 2 and Prolog 1 files. To create an indexed file with a prolog version other than Prolog 3, specify a Prolog 2 file. If all keys in the file are string keys, RMS provides a default of Prolog 1; in all other cases, Prolog 2 is the default.

If the file contains all string keys and Prolog 2 is requested, RMS attempts to create a Prolog 1 file only if no binary keys are present.

Note that RMS-11 and previous versions of RMS return error messages if requested to process Prolog 3 files.

If a failure is indicated, the file may be created, but it may not be opened for processing, depending on the nature of the failure.

Condition Values Returned

The following condition values can be returned. Use the Help Message utility to access online message descriptions. For more information about interpreting condition values, see Section 2.4.

The Delete service removes an existing record from a relative or indexed file. You cannot use this service when processing sequential files.

RAB64 Users (Alpha Only) On Alpha systems, RAB64 can replace the RAB or RAB prefix wherever it is used with the Delete service on OpenVMS Alpha systems.

Format

SYS$DELETE rab [,[err] [,suc]]

RETURNS

OpenVMS usage:	cond_value
type:	longword
access:	write only
mechanism:	by value

The value is returned in symbolic offset RAB$L_STS. Symbolic offset RAB$L_STV may contain additional status information.

Arguments

rab

OpenVMS usage:	rab
type:	longword (unsigned)
access:	modify
mechanism:	by reference

RAB control block whose contents are to be used as indirect arguments for the Delete service call. The rab argument is the address of the RAB control block.

err

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

AST-level error completion routine that the service invokes if the operation is unsuccessful. The err argument is the address of the entry mask of this user-written completion routine.

suc

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

AST-level success completion routine that the service invokes if the operation is successful. The suc argument is the address of the entry mask of this user-written completion routine.

Description

A Delete service always applies to the current record. Therefore, immediately before invoking the Delete service, you must establish the current record by issuing a Find or Get service.

Table RMS-11 lists the control block fields read as input by the Delete service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-11 Delete Service RAB Input Fields

Field Name	Option	Description
RAB$W_ISI		Internal stream identifier (required).
RAB$L_ROP		Record-processing options.
	RAB$V_ASY	Asynchronous: performs Delete service asynchronously.
	RAB$V_FDL	Fast delete (applies to indexed files).

Table RMS-12 lists the control block fields written as output by the Delete service.

Table RMS-12 Delete Service RAB Output Fields

Field Name	Description
RAB$L_STS	Completion status code (also returned in register 0).
RAB$L_STV	Status value.

Condition Values Returned

The following condition values can be returned. Use the Help Message utility to access online message descriptions. For more information about interpreting condition values, see Section 2.4.