[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Record Management Services Reference Manual


Previous Contents Index


$WAIT

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.

RMS$_BLN RMS$_CDA RMS$_EXT_ERR
RMS$_FAB RMS$_ISI RMS$_NORMAL
RMS$_OPNOTSUP RMS$_RAB RMS$_STR
RMS$_SUC    

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.


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


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
4523PRO_034.HTML