Document revision date: 30 March 2001

## 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:
> - You can skip records when you are accessing a file sequentially by making successive invocations of the Find service.
> - You can establish the current record context prior to invoking an Update, Delete, or Truncate service.
> - You can establish a random access starting point in a file for subsequent sequential access operations such as the Get service.

> 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

| privacy and legal statement |
4523PRO_025.HTML