Document revision date: 15 July 2002
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Record Management Services Reference Manual


Previous Contents Index

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.

RMS$_BLN RMS$_CDA RMS$_CHN
RMS$_DEV RMS$_DME RMS$_DNF
RMS$_DNR RMS$_DVI RMS$_ESA
RMS$_ESL RMS$_FAB RMS$_FNF
RMS$_IFI RMS$_NAM RMS$_NAML
RMS$_NAMLFSINV RMS$_NAMLFSSIZ RMS$_NAMLRSS
RMS$_NMF RMS$_NORMAL RMS$_PRV
RMS$_RMV RMS$_RSL RMS$_RSS
RMS$_RST RMS$_STR RMS$_SUC
RMS$_SUP RMS$_SUPPORT RMS$_SYS
RMS$_WCC RMS$_WLD RMS$_WLK

$RENAME

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.


1This field or option is not supported for DECnet for OpenVMS operations.

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.


1This field is not supported for DECnet for OpenVMS operations.

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.


1This field or option is not supported for DECnet for OpenVMS operations.

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.


1This field is not supported for DECnet for OpenVMS operations.


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.

RMS$_ACC RMS$_BLN RMS$_BUG_DDI
RMS$_CDA RMS$_CHN RMS$_DEV
RMS$_DIR RMS$_DME RMS$_DNA
RMS$_DNF RMS$_DNR RMS$_DVI
RMS$_ENT RMS$_ESA RMS$_ESS
RMS$_FAB RMS$FNA RMS$_FNM
RMS$_IDR RMS$_IFI RMS$_LNE
RMS$_NAM RMS$_NAML RMS$_NAMLESS
RMS$_NAMLFSINV RMS$_NAMLFSSIZ RMS$_NAMLRSS
RMS$_NET RMS$_NETFAIL RMS$_NMF
RMS$_NORMAL RMS$_PRV RMS$_QUO
RMS$_REENT RMS$_RLF RMS$_RMV
RMS$_RSS RMS$_RST RMS$_RUNDOWN
RMS$_STR RMS$_SUC RMS$_SUPPORT
RMS$_SYN RMS$_SYS RMS$_TYP
RMS$_VER RMS$_WLD  

$REWIND

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.

RMS$_ACT RMS$_ATR RMS$_ATW
RMS$_BLN RMS$_BOF RMS$_BUG_DAP
RMS$_CDA RMS$_DME RMS$_DNR
RMS$_DPE RMS$_EXT_ERR RMS$_IOP
RMS$_ISI RMS$_KRF RMS$_NET
RMS$_NETFAIL RMS$_NORMAL RMS$_OPNOTSUP
RMS$_PENDING RMS$_QUO RMS$_RAB
RMS$_RSA RMS$_STR RMS$_SUC
RMS$_SUP RMS$_SUPPORT RMS$_SYS
RMS$_WBE RMS$_WER RMS$_WLK


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4523PRO_033.HTML