Document revision date: 19 July 1999

The Wait service suspends image execution until an asynchronous file or record service completes. The same control block that is used with the asynchronous file or record service call is specified as the parameter for the Wait service. If it is an asynchronous file service, the control block is a FAB; if it is an asynchronous record service, the control block is a RAB. Upon completion of the service, RMS returns control to your program at the point following the Wait service call.

RAB64 Users (Alpha Only) On Alpha systems, RAB64 can replace the RAB or RAB prefix wherever it is used with the Wait service on OpenVMS Alpha systems.

Format

SYS$WAIT control-block

RETURNS

OpenVMS usage:	cond_value
type:	longword
access:	write only
mechanism:	by value

The value is returned in symbolic offset FAB$L_STS or RAB$L_STS. Symbolic offset FAB$L_STV or RAB$L_STV may contain additional status information.

Argument

control-block

type:
access:

fab or rab

OpenVMS usage:	fab or rab
type:	longword (unsigned)
access:	modify
mechanism:	by reference

FAB or RAB control block whose contents are to be used as indirect arguments for the Open service call. The fab or rab argument is the address of the FAB or RAB control block.

Description

The Wait service takes no arguments to define entry points for user-written completion routines; the completion routines are specified by the service being awaited.

Any completion routines specified on the operation being awaited are declared as ASTs before RMS returns control. They are executed before the Wait service completes unless ASTs are disabled. Completion routines are always executed as asynchronous system traps (ASTs).

Table RMS-99 lists the control block fields used as input by the Wait service for the FAB. For additional information on the fields accessed by this service, see Part 2 of this manual.

Table RMS-99 Wait Service FAB Input Fields

Field Name	Description
FAB$W_IFI	Internal file identifier (required).
FAB$L_STS	Status completion code.

Table RMS-100 lists the control block field written as output by the Wait service for the FAB.

Table RMS-100 Wait Service FAB Output Field

Field Name	Description
FAB$L_STS	Completion status code (also returned in register 0).

Table RMS-101 lists the control block fields used as input by the Wait service for the RAB. For additional information on the fields accessed by this service, see Part 2 of this manual.

Table RMS-101 Wait Service RAB Input Fields

Field Name	Description
RAB$W_ISI	Internal stream identifier (required).
RAB$L_STS	Status completion code.

Table RMS-102 lists the control block field written as output by the Wait service for the RAB.

Table RMS-102 Wait Service RAB Output Field

Field Name	Description
RAB$L_STS	Completion status code (also returned in register 0).

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.

The RMS completion status codes for the Wait service are determined by the service being awaited, unless the address of the FAB or RAB specified for the wait is different from that specified for the awaited operation. In this case, RMS$_NORMAL is returned.

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>,
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>,
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.

	privacy and legal statement
4523PRO_034.HTML