Document revision date: 15 July 2002

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.

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.

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

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.

	privacy and legal statement
4523PRO_026.HTML