Document revision date: 15 July 2002

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

	privacy and legal statement
4523PRO_036.HTML