Document revision date: 30 March 2001

## 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

| privacy and legal statement |
4523PRO_032.HTML