Document revision date: 30 March 2001

## OpenVMS Record Management Services Reference Manual

Previous | Contents | Index

## $READ

> The Read service retrieves a specified number of bytes from a file (beginning on a block boundary) and transfers them to memory. A Read service using block I/O can be performed on any file organization.

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

### Format

> SYS$READ 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 Read 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

> To use the Read service, you must do the following:
> 1. Supply a buffer area for transferring data (user record area address field) and specify the buffer size:
>    - To supply a 32-bit buffer address and a buffer size no greater than 65,535 bytes, use these fields:

>      User Buffer Address Field | User Buffer Size Field
>      --- | ---
>      RAB$L_UBF | RAB$W_USZ

>    - On OpenVMS Alpha systems, you can supply a 64-bit buffer address (or a 32-bit address sign-extended to 64 bits) and a buffer size up to 2**31-1 bytes. To do so, code -1 in RAB64$L_UBF and use these fields:

>      User Buffer Address Field | User Buffer Size Field
>      --- | ---
>      RAB64$PQ_UBF | RAB64$Q_USZ

> 2. Indicate the first virtual block number (VBN) for the transfer (bucket number field). This field is RAB$L_BKT or RAB64$L_BKT (available only on Alpha to accommodate 64-bit addressing). If the value for the VBN is 0, the transfer starts with the block indicated by the next block pointer (NBP).

> RAB Control Block Fields

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

> Table RMS-65 Read Service RAB Input Fields
> Field Name | Option | Description
> --- | --- | ---
> RAB$L_BKT |  | Bucket number: must contain the virtual block number of the first block to read. When this field has a value of 0, then the next block is read.
> RAB$W_ISI |  | Internal stream identifier (required).
> RAB$L_ROP |  | Record-processing option.
> | RAB$V_ASY | Asynchronous: performs Delete service asynchronously.
> RAB$L_UBF |  | User record buffer address. For block I/O, alignment of the user's record buffer on a page or at least a quadword boundary may improve performance.
> RAB$W_USZ |  | User record area size: indicates the length of the transfer, in bytes 1.

1Certain devices require that an even number of bytes be transferred. For further details, see the OpenVMS I/O User's Reference Manual.

Table RMS-66 lists the control block fields written as output by the Read service.

Table RMS-66 Read Service RAB Output Fields
Field Name | Description
--- | ---
RAB$L_RBF | Record address.
RAB$W_RFA | Record file address.
RAB$W_RSZ | Record size: indicates the actual number of bytes transferred.
RAB$L_STS | Completion status code (also returned in register 0).
RAB$L_STV | Status value.

RAB64 Control Block Fields (Alpha Only)

Table RMS-67 lists the Alpha-only RAB64 control block fields read as input by the Read service. These fields are comparable to the RAB fields described in Table RMS-65. For additional information on the fields accessed by this service, see Part 2.

Table RMS-67 Read Service RAB64 Input Fields (Alpha Only)
Field Name | Description
--- | ---
RAB64$B_BLN | This field must be initialized to RAB64$C_BLN64 in order for RAB64 fields to be used.
RAB64$L_BKT | Bucket number. Equates to RAB$L_BKT (see Table RMS-65).
RAB64$W_ISI | Internal stream identifier (required). Equates to RAB$W_ISI.
RAB64$L_ROP | Record-processing option. Equates to RAB$L_ROP (see Table RMS-65). The RAB64$V_ASY option is identical to RAB$V_ASY.
RAB64$L_UBF 1 | User record buffer address. This field must contain -1 if you want to use RAB64$PQ_UBF. For 32-bit addressing, this field equates to RAB$L_UBF (see Table RMS-65).
RAB64$PQ_UBF 1 | User record buffer 64-bit address (used if RAB64$L_UBF contains -1 ). This field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.
RAB64$W_USZ 1 | User record buffer size. This field is ignored in favor of RAB64$Q_USZ if RAB64$L_UBF contains -1 . Otherwise, this field equates to RAB$W_USZ (see Table RMS-65).
RAB64$Q_USZ 1 | User record buffer size. This field must be used when RAB64$L_UBF contains -1 and a value is specified in RAB64$PQ_UBF. (See Section 8.8 for more information.)

1One of the UBF fields must contain an address and the USZ field associated with it must contain a size.

Table RMS-68 lists the Alpha-only RAB64 control block fields written as output by the Read service. These fields are comparable to the RAB fields described in Table RMS-66.

Table RMS-68 Read Service RAB64 Output Fields (Alpha Only)
Field Name | Description
--- | ---
RAB64$L_RBF | Record buffer address is returned to this field if RAB64$L_UBF does not contain -1 . Equates to RAB$L_RBF.
RAB64$PQ_RBF | Record buffer address is returned to this field if RAB64$L_UBF contains -1 .
RAB64$W_RFA | Record file address. Equates to RAB$W_RFA.
RAB64$W_RSZ | Record buffer size is returned to this field if RAB64$L_UBF does not contain -1 . Equates to RAB$W_RSZ (see Table RMS-66).
RAB64$Q_RSZ | Record buffer size is returned to this field if RAB64$L_UBF contains -1 .
RAB64$L_STS | Completion status code. Equates to RAB$L_STS (see Table RMS-66).
RAB64$L_STV | Status value. Equates to RAB$L_STV.

### 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$_BLN | RMS$_BUG_DAP
RMS$_CDA | RMS$_CONTROLC | RMS$_CONTROLY
RMS$_DME | RMS$_DNR | RMS$_EOF
RMS$_FAC | RMS$_FTM | RMS$_IOP
RMS$_ISI | RMS$_NET | RMS$_NETFAIL
RMS$_NORMAL | RMS$_PBF | RMS$_PENDING
RMS$_RAB | RMS$_RER | RMS$_RSA
RMS$_STR | RMS$_SUC | RMS$_SUP
RMS$_SUPPORT | RMS$_SYS | RMS$_TMO
RMS$_UBF | RMS$_USZ | RMS$_WBE

## $RELEASE

> The Release service unlocks the record specified by the contents of the record file address (RAB$W_RFA) field of the RAB.

> RAB64 Users RAB64 can replace the RAB or RAB prefix wherever it is used with the Release service on OpenVMS Alpha systems.

### Format

> SYS$RELEASE 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 Release 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 Release service unlocks a specified record (see also the discussion of the Free service). If the named record is not locked, RMS returns a status code of RMS$_RNL.

> Table RMS-69 lists the control block fields used as input by the Release service. For additional information on the fields accessed by this service, see Part 2.

> Table RMS-69 Release 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 Release service asynchronously.

> Table RMS-70 lists the control block fields written as output by the Release service.

> Table RMS-70 Release Service RAB Output Fields
> Field Name | Description
> --- | ---
> RAB$L_STS | Completion status code (also returned in register 0).
> RAB$L_STV | Additional status information.

### 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$_BLN | RMS$_BUG_DAP
RMS$_CDA | RMS$_EXT_ERR | RMS$_ISI
RMS$_NET | RMS$_NETFAIL | RMS$_NORMAL
RMS$_OPNOTSUP | RMS$_PENDING | RMS$_RAB
RMS$_RNL | RMS$_RSA | RMS$_STR
RMS$_SUC | RMS$_SUP | RMS$_SUPPORT

## $REMOVE

> The Remove service deletes a file name from a directory. It is the reverse of the Enter service.

> Note The $REMOVE service is not supported for DECnet.

### Format

> SYS$REMOVE 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 Remove 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

> The Remove service searches for the first file name that matches the expanded name string and directory ID in the user's NAM or NAML block, and then it deletes the file name without deleting the actual file. The Remove service is similar to the Erase service, except that the Erase service also deletes the file after performing an implicit Remove. Note that you must close the file before invoking the Remove service (that is, the value of FAB$W_IFI must be 0).

> The Remove service accepts wildcard characters and search lists, and it is usually preceded by a call to the Parse service in order to fill in the appropriate fields of the NAM or NAML block. Because the Remove service returns the wildcard context field of the NAM or NAML block (NAM$L_WCC or NAML$L_WCC), the Remove service can be used on multiple successive calls to remove successive file names that match a wildcard file specification.

> Be careful when you mix calls to the Search and Remove services. For example, assume you invoke the following service sequence:

> 1. PARSE
> 2. SEARCH
> 3. REMOVE
> 4. SEARCH
> 5. REMOVE
> RMS responds by doing the following:
> 1. Searches for the first file specification that matches the expanded name string
> 2. Searches for and removes the second file specification
> 3. Searches for the third file specification
> 4. Searches for and removes the fourth file specification

> If you want to remove the directory entry of a file and you have that file's ID, then you can improve the speed of the Remove service by specifying the NAM bit in the FAB$L_FOP field. To do this properly, you must first parse the name of the file specification (to clear the NAM$W_FID or NAML$W_FID field), place the correct FID in the NAM or NAML block, and then perform the Remove service.

> Note The Remove service is not supported for DECnet for OpenVMS operations on files at remote OpenVMS systems.

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

> Table RMS-71 Remove Service FAB Input Fields
> Field Name | Description
> --- | ---
> FAB$L_FOP | File-processing option, FAB$V_NAM only. NAM or NAML block inputs: indicates that the NAM$W_FID field is used as input.
> FAB$W_IFI | Internal file identifier (must be zero).
> FAB$L_NAM | NAM or NAML block address.

> Table RMS-72 lists the FAB control block fields written as output by the Remove service.

> Table RMS-72 Remove 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-73 lists the NAM control block fields read as input by the Remove service.

> Table RMS-73 Remove Service NAM Input Fields
> Field Name | Description
> --- | ---
> NAM$W_DID | Directory identification; identifies the directory from which the file is to be removed.
> NAM$T_DVI | Device identification; identifies the device containing the directory from which the file is to be removed.
> NAM$L_ESA | Expanded string area address specifying the name, type, and version of the file to be removed.
> NAM$B_ESL | Expanded string length.
> NAM$W_FID | File identification: if nonzero and FAB$L_FOP field FAB$V_NAM bit is set in the input FAB, the first file in the directory with this file identification is removed.
> NAM$L_FNB | File name status bits (wildcard character bits only).
> NAM$L_RSA | Resultant string area address: specifies the name, type, and version number of the last file removed (required for wildcard character processing).
> NAM$B_RSL | Resultant string length.
> NAM$B_RSS | Resultant string area size.
> NAM$L_WCC | Wildcard character context value.

> Table RMS-74 lists the NAM control block fields written as output by the Remove service.

> Table RMS-74 Remove Service NAM Output Fields
> Field Name | Description
> --- | ---
> NAM$B_RSL | Resultant string length.
> NAM$L_WCC | Wildcard context value.

> The resultant string is moved to the buffer described by the NAM$L_RSA and NAM$B_RSS fields (only if both fields are nonzero on input).

> Table RMS-75 lists the NAML block fields used as input for the Remove service.

> Table RMS-75 Remove Service NAML Input Fields (Alpha Only)
> Field Name | Description
> --- | ---
> NAML$W_DID | Directory identification; identifies the directory from which the file is to be removed.
> NAML$T_DVI | Device identification; identifies the device containing the directory from which the file is to be removed.
> NAML$L_ESA | Expanded string area address specifying the name, type, and version of the file to be removed.
> NAML$B_ESL | Expanded string length.
> NAML$W_FID | File identification: if nonzero and FAB$L_FOP field FAB$V_NAM bit is set in the input FAB, the first file in the directory with this file identification is removed.
> NAML$L_FILESYS_NAME | File system name buffer address.
> NAML$L_FILESYS_NAME_ALLOC | File system name buffer size.
> NAML$L_FNB | File name status bits (wildcard character bits only).
> 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: specifies the name, type, and version number of the last file removed (required for wildcard character processing).
> NAML$B_RSL | Resultant string length.
> NAML$B_RSS | Resultant string area size.
> NAML$L_WCC | Wildcard character context value.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 4523PRO_031.HTML