 |
OpenVMS Record Management Services Reference
Manual
$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
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.
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-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.
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.
|
|
