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


$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

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