Document revision date: 15 July 2002

Table RMS-76 lists the NAML control block fields read as output by the Remove service.

Table RMS-76 Remove Service NAML Block Output Fields (Alpha Only)

Field Name	Description
NAML$L_FILESYS_NAME_SIZE	File system name 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.
NAML$L_WCC	Wildcard context 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.

You can use this service to change the name, type, or version of a file, or to move a file to another directory by changing its directory specification. However, note that you cannot use this service to move a file to another device.

Format

SYS$RENAME old-fab ,[err] ,[suc] ,new-fab

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

old-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 Rename service call. The old-fab argument is the address of the FAB control block that specifies the old file name.

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.

new-fab

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

The new-fab argument is the address of the FAB control block that specifies the new file name.

Note If you invoke the Rename service using the $RENAME macro and if you do not specify arguments, you must construct an additional field within your argument list to contain the address of the FAB that specifies the new file name. This additional field is placed in the argument list following the field for the success completion routine (see Part 1), and the argument count is set to 4.

Description

The Rename service performs the equivalent of two Parse services (old and new name), a Search service for the old directory, an Enter service to insert the new file name into the new directory, and a Remove service to delete the old file name from the old directory.

No wildcard character specifications are allowed. You can move a file from one directory to another using this service, but both directories must be on the same disk device.

If the Rename service is successful, the new directory entry is created and the old entry is deleted. If the service fails, the old entry remains and the new entry is deleted.

The following tables list the fields in FAB, NAM, and NAML blocks that the Rename service uses as input and output. In these tables, these blocks are called FAB1 and NAM1 for the old entry, and FAB2 and NAM2 for the new entry. For output, FAB2 is not used, although it must be in writable memory. To check or signal the completion codes in FAB$L_STS and FAB$L_STV, use the first FAB (FAB1).

The resultant file specification string for each of the names (old and new) is placed in the buffer described by the NAM$L_RSA (or NAML$L_LONG_RESULT) and NAM$B_RSS (or NAML$_LONG_RESULT_ALLOC) fields of the separate NAM or NAML blocks (only if both fields are nonzero).

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

Table RMS-77 Rename Service FAB Input Fields

Control Block	Field Name	Description
FAB1 and FAB2	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$W_IFI	Internal file identifier (must be zero).
	FAB$L_NAM	NAM or NAML block address.

Table RMS-78 lists the FAB control block fields written as output by the Rename service.

Table RMS-78 Rename Service FAB Output Fields

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

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

Table RMS-79 Rename Service NAM Input Fields

Control Block	Field Name	Option	Description
NAM1 and NAM2	NAM$L_ESA		Expanded string area address (must be nonzero).
	NAM$B_ESS		Expanded string area size (must be nonzero).
	NAM$B_NOP		NAM block options.
		NAM$V_NO_SHORT_UPCASE 1	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		Resultant string area address.
	NAM$B_RSS		Resultant string area size.
Related file NAM blocks	NAM$L_RSA		Related file resultant string area address.
	NAM$B_RSL		Related file resultant string length.
	NAM$L_FNB		Related file name status bits.

Table RMS-80 lists the NAM control block fields written as output by the Rename service.

Table RMS-80 Rename Service NAM Output Fields

Control Block	Field Name	Description
NAM1 and NAM2	NAM$W_DID 1	Directory identification.
	NAM$T_DVI 1	Device identification.
	NAM$B_ESL	Expanded string length.
	NAM$W_FID 1	File identification.
	NAM$L_FNB	File name status bits.
	NAM$B_RSL	Resultant string length.
	NAM$L_WCC	Wildcard context.
	NAM$W_FIRST_WILD_DIR 1	The topmost directory level to contain a wildcard.
	NAM$W_LONG_DIR_LEVELS 1	Total number of directories.

Table RMS-81 lists the NAML block fields used as input for the Rename service.

Table RMS-81 Rename Service NAML Input Fields (Alpha Only)

Control Block	Field Name	Option	Description
NAML1 and NAML2	NAML$L_ESA		Expanded string area address (must be nonzero).
	NAML$B_ESS		Expanded string area size (must be nonzero).
	NAML$B_NOP		NAM block options.
		NAML$V_NO_SHORT_UPCASE 1	Do not uppercase the directory and file specification in the NAML$L_ESA buffer.
	NAML$L_FILESYS_NAME 1		File system name buffer address.
	NAML$L_FILESYS_NAME_ALLOC 1		File system name size.
	NAML$L_INPUT_FLAGS 1		Additional flags specified as input.
	NAML$L_LONG_DEFNAME 1		Long default file specification string address.
	NAML$L_LONG_DEFNAME_SIZE 1		Long default file name size.
	NAML$L_LONG_EXPAND 1		Long expanded string area address.
	NAML$L_LONG_EXPAND_ALLOC 1		Long expanded string area size.
	NAML$L_LONG_FILENAME 1		Long file specification string address (used if FAB$L_FNA contains -1).
	NAML$L_LONG_FILENAME_SIZE 1		Long file specification string size.
	NAML$L_LONG_RESULT 1		Long resultant string area address.
	NAML$L_LONG_RESULT_ALLOC 1		Long resultant string area size. (used if FAB$L_DNA contains -1).
	NAML$L_RLF		Related file NAM or NAML block address.
	NAML$L_RSA		Resultant string area address.
	NAML$B_RSS		Resultant string area size.
Related file NAML blocks	NAML$L_RSA		Related file resultant string area address.
	NAML$B_RSL		Related file resultant string length.
	NAML$L_FNB		Related file name status bits.

Table RMS-82 lists the NAML control block fields written as output by the Rename service.

Table RMS-82 Rename Service NAML Output Fields (Alpha Only)

Control Block	Field Name	Description
NAML1 and NAML2	NAML$W_DID 1	Directory identification.
	NAML$T_DVI 1	Device identification.
	NAML$B_ESL	Expanded string length.
	NAML$W_FID 1	File identification.
	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$W_LONG_DIR_LEVELS 1	Total number of directories.
	NAML$L_LONG_EXPAND_SIZE 1	Long expanded string length.
	NAML$L_LONG_RESULT_SIZE 1	Long resultant string length.
	NAML$L_OUTPUT_FLAGS 1	Additional status bits passed as output.
	NAML$B_RSL	Resultant string length.
	NAML$L_WCC	Wildcard context.

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 Rewind service sets the context of a record stream to the first record in the file. RMS alters the context of the next record to indicate the first record as being the next record.

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

Format

SYS$REWIND 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 Rewind 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

The Rewind service implicitly performs the Flush and Free services, writing out all I/O buffers and releasing all locked records. This service is valid for all file organizations on disk volumes and for sequential files on tape volumes. For indexed files, the key of reference field establishes the index to be used for subsequent sequential accesses. You cannot rewind a unit record device (such as a card reader), indirectly accessed process-permanent files, or a file that was opened with the FAB$V_SQO option set.

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

Table RMS-83 Rewind Service RAB Input Fields

Field Name	Option	Description
RAB$W_ISI		Internal stream identifier (required).
RAB$B_KRF		Key of reference (used only with indexed files).
RAB$L_ROP		Record-processing options.
	RAB$V_ASY	Asynchronous: performs Rewind service asynchronously.

Table RMS-84 lists the control block fields written as output by the Rewind service.

Table RMS-84 Rewind 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_033.HTML