Document revision date: 15 July 2002

Table RMS-24 lists the NAM control block field read as output by the Enter service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-24 Enter Service NAM Output Field

Field Name	Description
NAM$B_RSL	Resultant string length.

Table RMS-25 lists the NAML block fields used as input for the Enter service.

Table RMS-25 Enter Service NAML Input Fields (Alpha Only)

Field Name	Description
NAML$W_DID	Directory identification: identifies the directory in which the file name is to be entered.
NAML$T_DVI	Device identification: identifies the device containing the directory in which the file name is to be entered.
NAML$L_ESA	Expanded string area address: contains the file name, type, and version to be entered.
NAML$B_ESL	Expanded string length.
NAML$W_FID	File identification: identifies the file to be entered into the directory.
NAML$L_INPUT_FLAGS	Additional flags specified as input.
NAML$L_LONG_EXPAND	Long expanded string area address.
NAML$L_LONG_EXPAND_ALLOC	Long expanded string area size.
NAML$L_LONG_RESULT	Long resultant string area address.
NAML$L_LONG_RESULT_ALLOC	Long resultant string area size.
NAML$L_RSA	Resultant string area address.
NAML$B_RSS	Resultant string size.

Table RMS-26 lists the NAML control block fields read as output by the Enter service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-26 Enter Service NAML Output Fields (Alpha Only)

Field Name	Description
NAML$L_LONG_RESULT_SIZE	Long resultant string length.
NAML$L_OUTPUT_FLAGS	Additional status bits passed as output.
NAML$B_RSL	Resultant string length.

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 Erase service deletes a disk file and removes the file's directory entry specified in the path to the file. If additional directory entries have been created for this file by the Enter service, you must use the Remove service to delete them.

Format

SYS$ERASE fab [,[err] [,suc]]

RETURNS

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

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

Arguments

fab

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

FAB control block whose contents are to be used as indirect arguments for the Erase service call. The fab argument is the address of the FAB 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

Using the Erase service to delete a file releases the file's allocated space for use by another file. The Erase service does not physically remove the data (as does overwriting or zeroing).

Note that the file must be closed before you invoke the Erase service (FAB$W_IFI must be zero). You can, however, delete a file that is currently open, if you issue a Close service and specify the FAB$L_FOP field FAB$V_DLT option. RMS does not allow you to delete files from magnetic tape volumes; they must be overwritten.

If a search list logical name is specified, the file is deleted only if it is found in the first resulting search list file specification.

A file that is open for write access by another process may be marked for delete by specifying the FAV$V_ERL file option for the erase service. The file deletion will occur when the file's reference count reaches zero.

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

Table RMS-27 Erase Service FAB Input Fields

Field Name	Option	Description
FAB$L_DNA		Default file specification string address.
FAB$B_DNS		Default file specification string size.
FAB$L_FNA		File specification string address.
FAB$B_FNS		File specification string size.
FAB$L_FOP		File-processing options.
	FAB$V_ERL	Erase regardless of lock: allows a file open for write access to be marked for delete.
	FAB$V_NAM 1	NAM block inputs: allows use of the NAM$W_DID, NAM$T_DVI, and NAM$W_FID fields.
FAB$W_IFI		Internal file identifier (must be 0).
FAB$L_NAM		NAM or NAML block address.

Table RMS-28 lists the FAB control block fields read as output by the Erase service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-28 Erase Service FAB Output Fields

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

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

Table RMS-29 Erase Service NAM Input Fields

Field Name	Option	Description
NAM$W_DID 1		Directory identification (input only if the FAB$L_FOP field FAB$V_NAM bit is set).
NAM$T_DVI 1		Device identification (input only if the FAB$L_FOP field FAB$V_NAM bit is set).
NAM$L_ESA		Expanded string area address.
NAM$B_ESS		Expanded string area size.
NAM$W_FID 1		File identification (input only if the FAB$L_FOP field FAB$V_NAM bit is set).
NAM$B_NOP		NAM block option.
	NAM$V_NO_SHORT_UPCASE	Do not uppercase the directory and file specification in the NAM$L_ESA buffer.
NAM$L_RLF		Related file NAM or NAML block address.
NAM$L_RSA		Related file resultant string address.
NAM$B_RSS		Related file resultant string size.
NAM$L_FNB		Related file file name status bits.

Note that the NAM block fields are used for output only if the name block address field is specified in the FAB.

Table RMS-30 lists the NAM control block fields read as output by the Erase service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-30 Erase Service NAM Output Fields

Field Name	Description
NAM$W_DID 1	Directory identification.
NAM$T_DVI 1	Device identification.
NAM$B_ESL	Expanded string length. If the NAM$L_ESA field and the NAM$B_ESS field are nonzero, and if the FAB$V_NAM bit is clear or the NAM$W_DID field contains a zero, RMS copies the expanded file specification string to the buffer specified by the input NAM$L_ESA field.
NAM$W_FIRST_WILD_DIR 1	The topmost directory level to contain a wildcard.
NAM$L_FNB	File name status bits.
NAM$L_LONG_DIR_LEVELS 1	Total number of directories.
NAM$B_RSL	Resultant string length (if NAM$L_RSA and NAM$B_RSS are both nonzero on input, the resultant file specification is copied to the buffer specified by NAM$L_RSA).

Table RMS-31 lists the NAML block fields used as input for the Erase service.

Table RMS-31 Erase Service NAML Input Fields (Alpha Only)

Field Name	Option	Description
NAML$W_DID 1		Directory identification (input only if the FAB$L_FOP field FAB$V_NAM bit is set).
NAML$T_DVI 1		Device identification (input only if the FAB$L_FOP field FAB$V_NAM bit is set).
NAML$L_ESA		Expanded string area address.
NAML$B_ESS		Expanded string area size.
NAML$W_FID 1		File identification (input only if the FAB$L_FOP field FAB$V_NAM bit is set).
NAML$L_FILESYS_NAME 1		File system name buffer address.
NAML$L_FILESYS_NAME_ALLOC 1		File system name buffer size.
NAML$L_FNB		Related 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_DEFAME_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 size.
NAML$B_NOP		NAML block option.
	NAML$V_NO_SHORT_UPCASE	Do not uppercase the directory and file specification in the NAML$L_ESA buffer.
NAML$L_RLF		Related file NAM or NAML block address.
NAML$L_RSA		Resultant string address.
NAML$B_RSS		Resultant string size.

Table RMS-32 lists the NAML control block fields read as output by the Erase service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-32 Erase Service NAML Output Fields (Alpha Only)

Field Name	Description
NAML$W_DID 1	Directory identification.
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 if the FAB$V_NAM bit is clear or the NAML$W_DID field contains a zero, RMS copies the expanded file specification string to the buffer specified by the input NAML$L_ESA field.
NAML$L_FILESYS_NAME_SIZE 1	File system name length.
NAML$W_FIRST_WILD_DIR 1	First wild directory.
NAML$L_FNB	File name status bits.
NAML$L_LONG_DIR_LEVELS 1	Total number of directories.
NAML$L_LONG_EXPAND_SIZE	Long expanded string length.
NAML$L_LONG_RESULT_SIZE	Long resultant string length.
NAML$L_OUTPUT_FLAGS	Additional status bits passed as output.
NAML$B_RSL	Resultant string length (if NAML$L_RSA and NAML$B_RSS are both nonzero on input, the resultant file specification is copied to the buffer specified by NAML$L_RSA).

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_025.HTML