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


$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:
  1. 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
  2. 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.

Table RMS-106 Write Service RAB64 Output Fields (Alpha Only)
Field Name Description
RAB64$W_RFA Record file address. Equates to RAB$W_RFA.
RAB64$L_STS Completion status code. Equates to RAB$L_STS (see Table RMS-104).
RAB64$L_STV Status value. Equates to RAB$L_STV (see 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:

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:

Note that R0 is usually used by the $NAML_STORE macro; thus, R0 is not preserved and does not contain a return status.


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_036.HTML