 |
OpenVMS Record Management Services Reference
Manual
$WRITE
The Write service transfers a user-specified number of bytes (beginning
on a block boundary) to an RMS file of any file organization.
RAB64 Users (Alpha
Only)
On Alpha systems, RAB64 can replace the RAB or RAB prefix wherever it
is used with the Write service on OpenVMS Alpha systems.
|
Format
SYS$WRITE 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 Write 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 Write service, you must do the following:
- Supply a buffer area 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_RBF
|
RAB$W_RSZ
|
- 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, put a -1 in RAB64$L_RBF and use these fields:
| User Buffer Address Field |
User Buffer Size Field |
|
RAB64$PQ_RBF
|
RAB64$Q_RSZ
|
- Indicate the virtual block number (VBN) of the first block to be
written in the 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).
A sequential file is automatically extended if you write a block past
the end of the currently allocated space when using block I/O (or
record I/O). For sequential files, RMS maintains a logical end of file
to correspond to the last block and highest byte written within the
block. For relative and indexed files, you must use the Extend service
when using block I/O.
RAB Control Block Fields
Table RMS-103 lists the control block fields read as input by the Write
service. For additional information on the fields accessed by this
service, see Part 2.
Table RMS-103 Write Service RAB Input Fields
| Field Name |
Option |
Description |
|
RAB$L_BKT
|
|
Bucket number: must contain the virtual block number of the first block
to be written.
|
|
RAB$W_ISI
|
|
Internal stream identifier.
|
|
RAB$L_RBF
|
|
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$L_ROP
|
|
Record-processing options.
|
|
|
RAB$V_ASY
|
Asynchronous: performs Write services asynchronously.
|
|
|
RAB$V_TPT
|
Truncate on Put: specifies that a Write service truncate the file after
the transferred data.
|
|
RAB$W_RSZ
|
|
Record size: indicates the transfer length, 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-104 lists the control block fields written as output by the
Write service.
Table RMS-104 Write Service RAB Output Fields
| Field Name |
Description |
|
RAB$W_RFA
|
Record file address.
|
|
RAB$L_STS
|
Completion status code (also returned in register 0).
|
|
RAB$L_STV
|
Status value: contains the actual number of bytes transferred if an
end-of-file error occurs.
|
RAB64 Control Block Fields (Alpha Only)
Table RMS-105 lists the Alpha-only RAB64 control block fields read as
input by the Write service. These fields are comparable to the RAB
fields described in Table RMS-103. For additional information on the
fields accessed by this service, see Part 2.
Table RMS-105 Write 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-103).
|
|
RAB64$W_ISI
|
Internal stream identifier. Equates to RAB$W_ISI.
|
|
RAB64$L_RBF
1
|
Record buffer address. This field must contain -1 if you want to use
RAB64$PQ_RBF. For 32-bit addressing, this field equates to RAB$L_RBF
(see Table RMS-103).
|
|
RAB64$PQ_RBF
1
|
Record buffer 64-bit address (used if RAB64$L_RBF contains -1 ). This
field can hold either a 64-bit address or a 32-bit address
sign-extended to 64 bits.
|
|
RAB64$L_ROP
|
Record-processing options. Equates to RAB$L_ROP and options described
in Table RMS-103. Options are identical except for the RAB64 prefix;
for example, option RAB64$V_ASY equates to RAB$V_ASY.
|
|
RAB64$W_RSZ
1
|
Record buffer size. This field is ignored in favor of RAB64$Q_RSZ if
RAB64$L_RBF contains -1 . Otherwise, this field equates to RAB$W_RSZ
(see Table RMS-103).
|
|
RAB64$Q_RSZ
1
|
Record buffer size. This field must be used when RAB64$L_RBF contains
-1 and a value is specified in RAB64$PQ_RBF. See Section 8.6 for more
information.
|
1One of the RBF fields must contain an address and the RSZ
field associated with it must contain a size.
Table RMS-106 lists the Alpha-only RAB64 control block fields written
as output by the Write service. These fields are comparable to the RAB
fields described in Table RMS-104.
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$_BUG_DAP
|
RMS$_CDA
|
|
RMS$_CONTROLC
|
RMS$_CONTROLO
|
RMS$_CONTROLY
|
|
RMS$_DME
|
RMS$_DNR
|
RMS$_EOF
|
|
RMS$_EXT
|
RMS$_FAC
|
RMS$_FTM
|
|
RMS$_FUL
|
RMS$_IOP
|
RMS$_ISI
|
|
RMS$_NET
|
RMS$_NETFAIL
|
RMS$_NORMAL
|
|
RMS$_PENDING
|
RMS$_RAB
|
RMS$_RBF
|
|
RMS$_RSA
|
RMS$_RSZ
|
RMS$_STR
|
|
RMS$_SUC
|
RMS$_SUP
|
RMS$_SUPPORT
|
|
RMS$_WBE
|
RMS$_WER
|
RMS$_WLK
|
Appendix A
RMS Control Block Macros
This appendix lists the format of each RMS control block macro and
includes special syntax notes that differ from the rules provided in
Part 1. Note that in this appendix the use of the term
"macro" refers to a VAX MACRO macro.
$FAB
The $FAB macro allocates storage for a FAB and initializes certain FAB
fields with defaults and user-specified values. No value is returned
for this assembly-time operation.
Format
$FAB ALQ=allocation-quantity,
BKS =bucket-size,
BLS =block-size,
CHAN
_MODE=channel-access-mode
CTX =user-context-value,
DEQ
=extension-quantity,
DNA =default-filespec-address,
DNM
=<filespec>,
DNS =default-filespec-string-size,
FAC
=<BIO BRO DEL GET PUT TRN UPD>,
FNA
=filespec-string-address,
FNM =<filespec>,
FNS
=filespec-string-size,
FOP =<CBT CIF CTG DFW DLT MXV NAM NEF
NFS OFP POS RCK RWC RWO SCF SPL SQO SUP TEF TMD TMP UFO WCK>,
FSZ =header-size,
GBC =global-buffer-count,
LNM
_MODE=logical-name-translation-access-mode,
MRN
=maximum-record-number,
MRS =maximum-record-size,
NAM
=nam-address,
ORG ={IDX|REL|SEQ},
RAT
=<BLK{CR|FTN|PRN}>,
RFM ={FIX|STM|STMCR|STMLF|UDF|VAR|VFC},
RTV =window-size,
SHR =<DEL GET MSE NIL PUT UPD UPI
NQL>,
XAB =xab-address
Arguments
For a description of the control block fields that correspond to the
$FAB macro arguments, see Chapter 4. In some cases, specific
default values are assigned automatically when you omit an argument. If
there is no specific default, RMS uses a default value of 0.
Arguments fall into three categories: values, addresses, and keywords.
Rules applicable to these argument categories are described in
Appendix B.
Note that multiple arguments can be specified for the FAC, FOP, RAT,
and SHR keywords, but the arguments must be enclosed within left angle
(<) and right angle (>) brackets. The DNM and FNM arguments must
also be delimited by these signs.
The DNM and FNM arguments contain ASCII characters and have no
corresponding field in the FAB. If the DNM argument is present, RMS
places its appropriate
address and size in the FAB$L_DNA and FAB$B_DNS fields. Similarly, if
the FNM argument is present, RMS places its appropriate address and
size in the FAB$L_FNA and FAB$B_FNS fields.
$FAB_STORE
The $FAB_STORE macro moves user-specified values into fields of the
specified FAB. The expanded $FAB_STORE code executes at run time on a
previously initialized (allocated) FAB, in contrast to the $FAB macro,
which initializes the FAB at assembly time. The $FAB_STORE macro must
reside in a code program section.
Format
$FAB_STORE fab=fab-address,
ALQ =#allocation-quantity,
BKS =#bucket-size,
BLS
=#block-size,
CHAN _MODE=#channel-access-mode
CTX
=user-context-value,
DEQ =#extension-quantity,
DNA
=default-filespec-address,
DNS =#default-filespec-string-size,
FAC =<BIO BRO DEL GET PUT TRN UPD>,
FNA
=filespec-string-address,
FNS =#filespec-string-size,
FOP
=<CBT CIF CTG DFW DLT MXV NAM NEF NFS OFP POS RCK RWC RWO SCF SPL
SQO SUP TEF TMD TMP UFO WCK>,
FSZ =#header-size,
GBC
=#global-buffer-count,
LNM
_MODE=#logical-name-translation-access-mode,
MRN
=#maximum-record-number,
MRS =#maximum-record-size,
NAM
=nam-address,
ORG ={IDX|REL|SEQ},
RAT
=<BLK{CR|FTN|PRN}>,
RFM ={FIX|STM|STMCR|STMLF|UDF|VAR|VFC},
RTV =#window-size,
SHR =<DEL GET MSE NIL PUT UPD UPI
NQL>,
XAB =xab-address
Arguments
For a description of the control block fields that correspond to the
$FAB_STORE macro arguments, see Chapter 4.
Arguments fall into several categories: values, addresses, keywords,
and the address of the control block to receive the specified
arguments. Rules applicable to these argument categories for the
control block store macros are described in Appendix B.
The FAB argument fab-address is required for the
$FAB_STORE macro and is not present for the $FAB macro. Conversely, the
DNM argument filespec and FNM argument
default-filespec are not available for the $FAB_STORE
macro, although you can use the DNA/DNS and FNA/FNS arguments to
specify file specifications at run time.
Note that R0 is usually used by the $FAB_STORE macro; thus, R0 is not
preserved and does not contain a return status.
$NAM
The $NAM macro allocates storage for a NAM block and initializes
certain NAM fields with default values and user-specified values. No
value is returned for this assembly-time operation.
Format
$NAM ESA=expanded-string-address,
ESS =expanded-string-size,
NOP =<NOCONCEAL PWD
NO_SHORT_UPCASE SRCHXABS SYNCHK>,
RLF
=related-file-nam-block-address,
RSA =resultant-string-address,
RSS =resultant-string-size
Arguments
For a description of the control block fields that correspond to the
$NAM macro arguments, see Chapter 5.
Arguments fall into three categories: values, addresses, and keywords.
Rules applicable to these argument categories are described in
Appendix B.
Note that multiple arguments can be specified for the NOP keyword, but
the arguments must be enclosed within left angle (<) and right angle
(>) brackets.
$NAM_STORE
The $NAM_STORE macro moves user-specified values into fields of the
specified NAM block. The expanded $NAM_STORE code executes at run time
on a previously initialized (allocated) NAM block, in contrast to the
$NAM macro, which initializes a NAM block at assembly time. The
$NAM_STORE macro must reside in a code program section.
Format
$NAM_STORE NAM=nam-address,
DID =#directory-identification,
DVI =#device-identification,
ESA =expanded-string-address,
ESS =#expanded-string-size,
FID =#file-identification,
NOP =<NOCONCEAL NO_SHORT_UPCASE
PWD SRCHXABS SYNCHK>,
RLF =related-file-nam-block-address,
RSA =resultant-string-address,
RSS =#resultant-string-size
Arguments
For a description of the control block fields that correspond to the
$NAM_STORE macro arguments, see Chapter 5.
Arguments fall into several categories: values, addresses, keywords,
and the address of the control block to receive the specified
arguments. Rules applicable to these argument categories for the
control block store macros are described in Appendix B.
The NAM argument nam-address is required for the
$NAM_STORE macro and is not present for the $NAM macro. Also, the
following $NAM_STORE argument fields are not available for the $NAM
macro:
- The DID argument directory-identification sets the
NAM$W_DID field, which is a 3-word field used when the FAB$L_FOP field
FAB$V_NAM option is set. This argument is usually specified by its
symbolic address. If a register is used to contain a value for the
NAM$W_DID field, do not use R12, because two contiguous registers must
be used to contain the value of this 3-word field. Note that you cannot
use the byte, word, or longword displacements for an offset, or for
indexed or deferred addressing.
- The DVI argument device-identification sets the
NAM$T_DVI field, which is a 16-byte field used when the FAB$L_FOP field
FAB$V_NAM option is set. This argument must be passed by its symbolic
address. A register must not be specified to contain a value for this
argument.
- The FID argument file-identification sets the
NAM$W_FID field, which is a 3-word field used when the FAB$L_FOP field
FAB$V_NAM option is set. This argument is specified by its symbolic
address. If a register is used to contain a value for the NAM$W_FID
field, do not use R12, because two contiguous registers must be used to
contain the value of this 3-word field. Note that you cannot use the
byte, word, or longword displacements for an offset, or for indexed or
deferred addressing.
Note that R0 is usually used by the $NAM_STORE macro; thus, R0 is not
preserved and does not contain a return status.
$NAML
The $NAML macro allocates storage for a NAML block and initializes
certain NAML fields with default values and user-specified values.
Format
$NAML ESA=expanded-string-address,
ESS =expanded-string-size,
NOP =<NOCONCEAL PWD
NO_SHORT_UPCASE SRCHXABS SYNCHK>,
RLF
=related-file-nam-block-address,
RSA =resultant-string-address,
RSS =resultant-string-size,
FILESYS _NAME=file system name
buffer address,
FILESYS _NAME_ALLOC=file system name buffer size,
INPUT _FLAGS=<NO_SHORT_OUTPUT>,
LONG _DEFNAME=long
default file specification string address,
LONG _DEFNAME_SIZE=long
default file specification string size,
LONG _FILENAME=long file
specification string address,
LONG _FILENAME_SIZE=long file
specification string size,
LONG _EXPAND=long expanded string area
address,
LONG _EXPAND_ALLOC=long expanded string area size,
LONG _RESULT=long resultant string area address,
LONG
_RESULT_ALLOC=long resultant string area size,
USER _CONTEXT=user
context
Arguments
For a description of the control block fields that correspond to the
$NAML macro arguments, see Chapter 6.
Arguments fall into three categories: values, addresses, and keywords.
Rules applicable to these argument categories are described in Appendix
B.
Note that multiple arguments can be specified for the NOP keyword, but
the arguments must be enclosed with left angle (<) and right angle
(>) brackets.
$NAML_STORE
The $NAML_STORE macro moves user-specified values into fields of the
specified NAML block. The expanded $NAML_STORE code executes at run
time on a previously initialized (allocated) NAML block, in contrast to
the $NAML macro, which initializes a NAML block at assembly time. The
$NAML_STORE macro must reside in a code program section.
Format
$NAML_STORE NAM=naml-address,
DID =#directory-identification,
DVI =#device-identification,
ESA =expanded-string-address,
ESS =#expanded-string-size,
FID =#file-identification,
NOP =<NOCONCEAL NO_SHORT_UPCASE
PWD SRCHXABS SYNCHK>,
RLF =related-file-nam-block-address,
RSA =resultant-string-address,
RSS =#resultant-string-size,
FILESYS _NAME=file system name buffer address,
FILESYS
_NAME_ALLOC=#file system name buffer size,
INPUT
_FLAGS=<NO_SHORT_OUTPUT>,
LONG _DEFNAME=long default file
specification string address,
LONG _DEFNAME_SIZE=#long default
file specification string size,
LONG _FILENAME=long file
specification string address,
LONG _FILENAME_SIZE=#long file
specification string size,
LONG _EXPAND=long expanded string area
address,
LONG _EXPAND_ALLOC=#long expanded string area size,
LONG _RESULT=long resultant string area address,
LONG
_RESULT_ALLOC=#long resultant string area size,
USER
_CONTEXT=#user context
Arguments
For a description of the control block fields that correspond to the
$NAML_STORE macro arguments, see Chapter 6.
Arguments fall into several categories: values, addresses, keywords,
and the address of the control block to receive the specified
arguments. Rules applicable to these argument categories for the
control block store macros are described in Appendix B.
The NAML argument naml-address is required for the
$NAML_STORE macro and is not present for the $NAML macro. Also, the
following $NAML_STORE argument fields are not available for the $NAML
macro:
- The DID argument directory-identification sets the
NAML$W_DID field, which is a 3-word field used when the FAB$L_FOP field
FAB$V_NAM option is set. This argument is usually specified by its
symbolic address. If a register is used to contain a value for the
NAML$W_DID field, do not use R12, because two contiguous registers must
be used to contain the value of this 3-word field. Note that you cannot
use the byte, word, or longword displacements for an offset, or for
indexed or deferred addressing.
- The DVI argument device-identification sets the
NAML$T_DVI field, which is a 16-byte field used when the FAB$L_FOP
field FAB$V_NAM option is set. This argument must be passed by its
symbolic address. A register must not be specified to contain a value
for this argument.
- The FID argument file-identification sets the
NAML$W_FID field, which is a 3-word field used when the FAB$L_FOP field
FAB$V_NAM option is set. This argument is specified by its symbolic
address. If a register is used to contain a value for the NAML$W_FID
field, do not use R12, because two contiguous registers must be used to
contain the value of this 3-word field. Note that you cannot use the
byte, word, or longword displacements for an offset, or for indexed or
deferred addressing.
Note that R0 is usually used by the $NAML_STORE macro; thus, R0 is not
preserved and does not contain a return status.
|
