OpenVMS Record Management Services Reference Manual

Document revision date: 15 July 2002

OpenVMS Record Management Services Reference Manual

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:

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

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 ¹.

User Buffer Address Field	User Buffer Size Field
RAB$L_UBF	RAB$W_USZ

User Buffer Address Field	User Buffer Size Field
RAB64$PQ_UBF	RAB64$Q_USZ

**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 ¹.

¹Certain 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.

**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 ¹ 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 ¹ 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 ¹ 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 ¹ 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.)

**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 ¹	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 ¹	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 ¹	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 ¹	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.)

¹One 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.

**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.

**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 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:

PARSE
SEARCH
REMOVE
SEARCH
REMOVE
RMS responds by doing the following:

Searches for the first file specification that matches the expanded name string
Searches for and removes the second file specification
Searches for the third file specification
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_032.HTML

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

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

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

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

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.

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

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.

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.