Document revision date: 15 July 2002

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

Table RMS-9 Create Service NAML Input Fields (Alpha Only)

Field Name	Option	Description
NAML$W_DID 1		Directory identification (input only if the FAB$L_FOP FAB$V_NAM option is set).
NAML$T_DVI 1		Device identification (input only if the FAB$L_FOP FAB$V_NAM option is set).
NAML$L_ESA		Expanded string area address.
NAML$B_ESS		Expanded string area size.
NAML$L_FILESYS_NAME 1		File system file name.
NAML$L_FILESYS_NAME_ALLOC 1		File system file name buffer size.
NAML$L_FNB		File name status bits.
NAML$L_INPUT_FLAGS		Additional flags specified as input.
NAML$L_LONG_DEFNAME		Long default file specification string address (used if FAB$L_DNA contains -1).
NAML$L_LONG_DEFNAME_SIZE		Long default file specification string size.
NAML$L_LONG_EXPAND		Long expanded string area address.
NAML$L_LONG_EXPAND_ALLOC		Long expanded string area size.
NAML$L_LONG_FILENAME		Long file specification string address (used if FAB$L_FNA contains -1).
NAML$L_LONG_FILENAME_SIZE		Long file specification string size.
NAML$L_LONG_RESULT		Long resultant string area address.
NAML$L_LONG_RESULT_ALLOC		Long resultant string area.
NAML$L_LONG_RESULT_SIZE		Long resultant string length.
NAML$B_NOP		NAML block options.
	NAML$V_PWD	Password: indicates that a password contained in a DECnet for OpenVMS access control string, if present in a file specification, is to be left unaltered in the expanded and resultant strings (instead of being replaced by the word "password").
	NAML$V_NOCONCEAL	Do not conceal device name: indicates that when a concealed device logical name is present, the concealed device logical name is to be replaced by the actual physical device name in the resultant string.
	NAML$V_NO_SHORT_UPCASE 1	Do not uppercase the directory and file specification in the NAM$L_ESA buffer.
NAML$L_RLF		Related file NAM or NAML block address.
NAML$L_RSA		Resultant string address.
NAML$B_RSL		Resultant string length.
NAML$B_RSS		Resultant string area size.

Table RMS-10 Create Service NAML Output Fields (Alpha Only)

Field Name	Description
NAML$B_DEV	Size of file specification device string.
NAML$L_DEV	Address of file specification device string.
NAML$W_DID 1	Directory identification.
NAML$B_DIR	Size of file specification directory string.
NAML$L_DIR	Address of file specification directory string.
NAML$T_DVI 1	Device identification.
NAML$B_ESL	Expanded string length. If the NAML$L_ESA field and the NAML$B_ESS field are nonzero, and you do not select the FAB$V_NAM option, or if the NAML$W_DID field is clear when you invoke the Create service, RMS copies the expanded file specification string to the buffer specified by the NAML$L_ESA field.
NAML$W_FID 1	File identification.
NAM$W_FIRST_WILD_DIR 1	First wild directory.
NAML$L_FILESYS_NAME_SIZE 1	File system name size.
NAML$L_FNB	File name status bits. This is an output field from the Create service only if the NAM bit in FAB$L_FOP field is clear, or if the NAML$W_DID field is clear when you invoke the Create service.
NAML$L_LONG_DEV	Long device string address.
NAML$L_LONG_DEV_SIZE	Long device string size.
NAML$L_LONG_DIR	Long directory string address.
NAML$W_LONG_DIR_LEVELS 1	Total number of directory levels.
NAML$L_LONG_DIR_SIZE	Long directory string size.
NAML$L_LONG_EXPAND_SIZE	Long expanded string length.
NAML$L_LONG_NAME	Long file name string address.
NAML$L_LONG_NAME_SIZE	Long file name string length.
NAML$L_LONG_NODE 1	Long node name string address.
NAML$L_LONG_NODE_SIZE	Long node name string length.
NAML$L_LONG_RESULT_SIZE 1	Long resultant string length.
NAML$L_LONG_TYPE	Long file type string length.
NAML$L_LONG_TYPE_SIZE	Long file type string address.
NAML$L_LONG_VER	Long file version string address.
NAML$L_LONG_VER_SIZE	Long file version string length.
NAML$B_NAME	Size of file specification name string.
NAML$L_NAME	Address of file specification name string.
NAML$B_NODE	Size of file specification node string.
NAML$L_NODE	Address of file specification node string.
NAML$L_OUTPUT_FLAGS	Output flags.
NAML$B_RSL	Resultant string length. If the NAML$L_RSA field and the NAML$B_RSS field are both nonzero on input, the resultant file specification is copied to the buffer specified by NAML$L_RSA.
NAML$B_TYPE	Size of file specification type string.
NAML$L_TYPE	Address of file specification type string.
NAML$B_VER	Size of file specification version string.
NAML$L_VER	Address of file specification version string.

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.

	privacy and legal statement
4523PRO_023.HTML