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


$EXTEND

The Extend service increases the amount of space allocated to a disk file. This service is most useful for extending relative files and indexed files when you are doing block I/O transfers using the Write service.

Format

SYS$EXTEND fab [,[err] [,suc]]


RETURNS


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

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


Arguments

fab


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

FAB control block whose contents are to be used as indirect arguments for the Extend service call. The fab argument is the address of the FAB 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

When a program adds data to a file using record I/O operations, RMS invokes the Extend service to provide additional file space, if needed, regardless of the file organization. But, when data is added using block I/O operations, RMS provides additional file space for sequential files only. To obtain additional file space when using block I/O, the program must invoke the Extend service.

You might also want to consider using the Extend service for all file organizations when you want to extend a file for performance reasons, such as placing a large file extent (an extended part of a file) contiguous with the file.

In order for a program to invoke the Extend service, it must open the file (FAB$W_IFI must not be 0); otherwise, an error occurs. RMS also requires that the file access field (FAB$B_FAC) specify either put access (FAB$V_PUT) or update access (FAB$V_UPD) before permitting file extensions.

The program uses the appropriate allocation quantity field (FAB$L_ALQ or XAB$L_ALQ) to specify the number of blocks that RMS uses to extend a file.

You can specify other attributes, such as how and where the additional space is allocated. For example, you can specify whether you want the additional space allocated contiguously. If you specify contiguous space and the additional space is not available, the operation fails.

When the program uses an allocation control XAB, the XAB's allocation quantity (XAB$L_ALQ) and allocation options (XAB$B_AOP, XAB$V_CBT, and XAB$V_CTG bits) are used instead of the corresponding options specified in the FAB. You can specify multiple XABs to extend separate areas of indexed files.

If no XABALL is present on the extend of an indexed file that is opened for I/O record access, RMS extends Area 0 of the file. If block I/O access is specified, RMS extends the file but does not affect the area descriptor. If no XABALL is present and you have not specified either of the contiguity options (FAB$V_CBT, FAB$V_CGT), RMS requests placement control to position the extension as near as possible to the last block allocated to the file.

Table RMS-33 lists the control block fields read as input by the Extend service. For additional information on the fields accessed by this service, see Part 2 of this manual.

Table RMS-33 Extend Service FAB Input Fields
Field Name Description
FAB$L_ALQ Allocation quantity. Ignored if an allocation XAB is present.
FAB$L_FOP File-processing options. Checked to see whether the FAB$V_CTG or FAB$V_CBT bit is set to indicate contiguous allocation (ignored for allocation XAB).
FAB$W_IFI Internal file identifier (must not be 0).
FAB$L_XAB Extended attribute block address. Only an allocation XAB (XABALL) is processed.

Table RMS-34 lists the control block fields written as output by the Extend service.

Table RMS-34 Extend Service FAB Output Fields
Field Name Description
FAB$L_ALQ Allocation quantity. Contains the actual extension allocation value if no allocation XAB is present.
FAB$L_STS Completion status code (also returned in register 0).
FAB$L_STV Status value. Contains the total number of blocks allocated, totaled across all allocation XABs.


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$_AID RMS$_ALN
RMS$_ALQ RMS$_AOP RMS$_ATR
RMS$_ATW RMS$_BLN RMS$_BUG_DAP
RMS$_CDA RMS$_COD RMS$_DME
RMS$_EXT RMS$_FAB RMS$_FAC
RMS$_FUL RMS$_IFI RMS$_IMX
RMS$_IOP RMS$_LEX RMS$_NET
RMS$_NETFAIL RMS$_NORMAL RMS$_PLG
RMS$_RPL RMS$_STR RMS$_SUC
RMS$_SUP RMS$_SUPPORT RMS$_SYS
RMS$_WBE RMS$_WER RMS$_WLK
RMS$_WPL RMS$_XAB  

$FIND

The Find service locates a specified record in a file and returns its record file address in the RAB$W_RFA field of the RAB. The Find service can be used with all file organizations.

RAB64 Users (Alpha Only)

On Alpha systems, RAB64 can replace the RAB or RAB prefix wherever it is used with the Find service on OpenVMS Alpha systems.

Format

SYS$FIND 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 Find 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

The Find service gives you the following functional capabilities:

When you follow the Find service with a sequential access operation, such as the Get service, the current record context is established by the Find service and the sequential access operation establishes a new sequential access context. Conversely, when you follow the Find service with a nonsequential access operation such as a Delete service or an Update service, the sequential access context remains the same as it was prior to the Find service.

RAB Control Block Fields

Table RMS-35 lists the control block fields read as input by the Find service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-35 Find Service RAB Input Fields
Field Name Option Description
RAB$W_ISI   Internal stream identifier (required).
RAB$L_KBF   Key buffer address (used only if the RAB$B_RAC field contains RAB$C_KEY or if RAB$B_RAC contains RAB$C_SEQ and the RAB$L_ROP field RAB$V_LIM option is set).
RAB$B_KRF   Key of reference (used only with indexed files and if RAB$B_RAC contains RAB$C_KEY).
RAB$B_KSZ   Key size (used only if the RAB$B_RAC field contains RAB$C_KEY or if RAB$B_RAC contains RAB$C_SEQ and the RAB$L_ROP field RAB$V_LIM option is set).
RAB$L_PBF 1   Prompt buffer address (applies to terminal devices only).
RAB$B_PSZ 1   Prompt buffer size (applies to terminal devices only).
RAB$B_RAC   Record access mode (RAB$C_SEQ, RAB$C_KEY, RAB$C_RFA) 2.
RAB$W_RFA   Record file address (used only if the RAB$B_RAC field contains RAB$C_RFA).
RAB$L_ROP   Record-processing options.
  RAB$V_ASY Asynchronous: performs Find services asynchronously.
  RAB$V_CVT 1 Convert: changes characters to uppercase for a Find service to a terminal device.
  RAB$V_KGE 3 Key is greater than or equal to compared value (applies only to indexed files).
  RAB$V_KGT 4 Key is greater than compared value (applies only to indexed files). If neither RAB$V_KGE nor RAB$V_KGT is specified, a key equal match is made.
  RAB$V_LIM Limit: the key value described by the KBF and KSZ fields is compared to the value in the sequentially-accessed record.
  RAB$V_NLK No lock: specifies that the record accessed through the Find service is not to be locked.
  RAB$V_NXR Nonexistent record processing: specifies that if the record accessed directly through a Find service does not exist, the service is to be performed anyway.
  RAB$V_PMT 1 Prompt indicates that the contents of the prompt buffer are to be used as a prompt for a Find service to a terminal device.
  RAB$V_PTA 1 Purge type-ahead buffer: eliminates any information that may be in the type-ahead buffer for a Find service to a terminal device.
  RAB$V_RAH 1 Read ahead: used with multiple buffers to indicate read-ahead operations (sequential files only).
  RAB$V_REA Lock for read: allows other users read access to the record.
  RAB$V_REV Reverses search direction for random keyed access operations when used with either RAB$V_KGE or RAB$V_KGT (applies only to indexed files).
  RAB$V_RLK Read of locked record allowed: specifies that a locked record can be read by other users.
  RAB$V_RNE 1 Read no echo: indicates that input data entered on the keyboard is not displayed on the terminal device.
  RAB$V_RNF 1 Read no filter: indicates that Ctrl/U, Ctrl/R, and DELETE are not to be considered control commands on terminal input, but are to be passed to the application program.
  RAB$V_RRL Read regardless of lock: read the record even if another stream has locked the record.
  RAB$V_TMO 1 Timeout: indicates that the contents of the timeout period field (RAB$B_TMO) is to be used on a Find request for a locked record (when the RAB$V_WAT option is also specified) or for a terminal or mailbox device.
  RAB$V_ULK Manual unlocking: specifies that a record cannot be unlocked automatically.
  RAB$V_WAT Wait: if record is locked, wait until it is available.
RAB$W_ROP_2 1   Extended record-processing options.
  RAB$V_NQL No query locking.
  RAB$V_NODLCKWT No deadlock wait.
  RAB$V_NODLCKBLK No deadlock blocking.
RAB$B_TMO 1   Timeout period: indicates the maximum number of seconds that RMS can spend to complete a Find request.


1This field is not supported for DECnet for OpenVMS operations.
2The default for the RAB$B_RAC field is RAB$C_SEQ.
3This symbolic offset is logically synonymous with RAB$V_EQNXT.
4This symbolic offset is logically synonymous with RAB$V_NXT.

Table RMS-36 lists the control block fields written as output by the Find service.

Table RMS-36 Find Service RAB Output Fields
Field Name Description
RAB$L_BKT Bucket code: set to the relative record number for sequentially accessed relative files.
RAB$W_RFA Record file address.
RAB$L_STS Completion status code (also returned in register 0).
RAB$L_STV Status value.

The record address (RAB$L_RBF) field and the record size (RAB$W_RSZ) field are undefined after a Find service.

RAB64 Control Block Fields (Alpha Only)

Table RMS-37 lists the Alpha-only RAB64 control block fields read as input by the Find service. These fields are comparable to the RAB fields described in Table RMS-35. For additional information on the fields accessed by this service, see Part 2.

Table RMS-37 Find 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$W_ISI Internal stream identifier (required). Equates to RAB$W_ISI.
RAB64$L_KBF Key buffer address. This field must contain -1 if you want to use RAB64$PQ_KBF. For 32-bit addressing, this field equates to RAB$L_KBF (see Table RMS-35).
RAB64$PQ_KBF Key buffer 64-bit address (used if RAB64$L_KBF contains -1 ). This field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.
RAB64$B_KRF Key of reference. Equates to RAB$B_KRF (see Table RMS-35).
RAB64$B_KSZ Key buffer size. Equates to RAB$B_KSZ (see Table RMS-35).
RAB64$L_PBF 1 Prompt buffer address. Equates to RAB$L_PBF (see Table RMS-35).
RAB64$B_PSZ 1 Prompt buffer size. Equates to RAB$B_PSZ (see Table RMS-35).
RAB64$B_RAC Record access mode. Equates to RAB$B_RAC (see Table RMS-35).
RAB64$W_RFA Record file address. Equates to RAB$W_RFA (see Table RMS-35).
RAB64$L_ROP Record-processing options. Equates to RAB$L_ROP and options described in Table RMS-35. Options are identical except for the RAB64 prefix; for example, option RAB64$V_ASY equates to RAB$V_ASY.
RAB64$W_ROP_2 1 Extended record-processing options. Equates to RAB64$W_ROP_2 and options described in Table RMS-35. Options are identical except for the RAB64 prefix; for example, option RAB64$V_NODLCKWT equates to RAB$V_NODLCKWT.
RAB64$B_TMO 1 Timeout period. Equates to RAB$B_TMO (see Table RMS-35).


1This field is not supported for DECnet for OpenVMS operations.

Table RMS-38 lists the Alpha-only RAB64 control block fields written as output by the Find service. These fields are comparable to the RAB fields described in Table RMS-36.

Table RMS-38 Find Service RAB64 Output Fields (Alpha Only)
Field Name Description
RAB64$L_BKT Bucket code. Equates to RAB$L_BKT (see Table RMS-36).
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-36).
RAB64$L_STV Status value. Equates to RAB$L_STV.

The record address (RAB64$L_RBF) field and the record size (RAB64$W_RSZ) field are undefined after a Find service.


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$_ANI RMS$_ATR
RMS$_ATW RMS$_BES RMS$_BLN
RMS$_BUG RMS$_BUG_DAP RMS$_CDA
RMS$_CHK RMS$_CONTROLC RMS$_CONTROLY
RMS$_DEADLOCK RMS$_DEL RMS$_DME
RMS$_DNR RMS$_EOF RMS$_EXENQLM
RMS$_EXT_ERR RMS$_FAC RMS$_FTM
RMS$_IBF RMS$_IDXSEARCH RMS$_IOP
RMS$_IRC RMS$_ISI RMS$_KBF
RMS$_KEY RMS$_KRF RMS$_KSZ
RMS$_MRN RMS$_NET RMS$_NETFAIL
RMS$_NORMAL RMS$_OK_ALK RMS$_OK_DEL
RMS$_OK_LIM RMS$_OK_RLK RMS$_OK_RNF
RMS$_OK_RRL RMS$_OK_WAT RMS$_OPNOTSUP
RMS$_PBF RMS$_PENDING RMS$_PES
RMS$_PLG RMS$_RAB RMS$_RAC
RMS$_REF RMS$_RER RMS$_RFA
RMS$_RHB RMS$_RLK RMS$_RNF
RMS$_ROP RMS$_RPL RMS$_RRV
RMS$_RSA RMS$_SQO RMS$_STR
RMS$_SUC RMS$_SUP RMS$_SUPPORT
RMS$_SYS RMS$_TMO RMS$_TRE
RMS$_WBE RMS$_WER RMS$_WLK


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