Document revision date: 19 July 1999

The Space service lets you space (skip) a tape file forward or backward a specified number of blocks.

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

Format

SYS$SPACE 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 Space 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 Space service is intended primarily for use with magnetic tape files; the tape is skipped forward or backward the number of blocks specified in the bucket number field. (The size of each block on any tape is specific to that tape and is defined on the tape itself, not by OpenVMS or RMS.) If the value in this field is positive, the tape skips forward; if the value is negative, the tape skips backward. For disk files, the next block pointer (NBP) is updated to reflect the new sequential operation position.

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

Table RMS-91 Space Service RAB Input Fields

Field Name	Option	Description
RAB$L_BKT		Bucket code. Indicates the number of blocks to space forward (positive value) or backward (negative value).
RAB$W_ISI		Internal stream identifier (required).
RAB$L_ROP		Record-processing options.
	RAB$V_ASY	Asynchronous. Performs Space service asynchronously.

Table RMS-92 lists the control block fields written as output by the Space service.

Table RMS-92 Space Service RAB Output Fields

Field Name	Description
RAB$L_STS	Completion status code (also returned in register 0).
RAB$L_STV	Status value (the absolute number of blocks actually skipped; the value is always positive).

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 Truncate service shortens a sequential file.

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

Format

SYS$TRUNCATE 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 Truncate 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 Truncate service shortens a sequential file by resetting the logical end-of-file position to the beginning of the current record. You can then append records to the file by issuing successive Put services.

The record access mode determines the current record position for the Truncate service as follows:

• In sequential record access mode, you can only use this service immediately after setting the context of the current record by successfully executing a Get or Find service.
• In random-access-by-key mode, RMS establishes the current record position as defined by the key of reference or the relative record number (RRN), as applicable.
• In random-access-by-RFA (record file address) mode, RMS establishes the current record position as defined by the RFA.

The Truncate service does not deallocate space between the end-of-file position and the physical end of the file, nor does it overwrite the records between the end-of-file position and the physical end of the file with an erase pattern. You can read records from the end-of-file position to the physical end of the file by setting the end-of-file position to the highest block allocated using the DCL command SET FILE/END_OF_FILE. If you want to erase the data between the logical end of the file and the physical end of the file, either you must delete the file and write a new one, or your application program must overwrite the records you want to delete.

The Truncate service requires that the file access (FAB$B_FAC) field specify a truncate access (FAB$V_TRN). Truncating a file opened for shared access may have unexpected results if other accessors are currently accessing the file beyond the end-of-file position.

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

Table RMS-93 Truncate Service RAB Input Fields

Field Name	Option	Description
RAB$W_ISI		Internal stream identifier (required).
RAB$L_ROP		Record-processing options.
	RAB$V_ASY	Asynchronous: performs Truncate service asynchronously.

Table RMS-94 lists the control block fields written as output by the Truncate service.

Table RMS-94 Truncate Service RAB Output Fields

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

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 Update service allows you to modify the contents of an existing record in a file residing on a disk device.

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

Format

SYS$UPDATE 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 Update 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 record to be updated by the Update service must first be locked by this stream, using either a Find or Get service. When updating a record, you must use move mode (not locate mode); that is, you must supply a buffer.

The record length for sequential files cannot change. For relative files with variable-length or variable with fixed-length control records, the length of the replacement record can be different from the length of the original record, but cannot be larger than the maximum size you set when you created the file.

For stream format files, the Update service functions in the same manner as the Put service, with one exception: when using the Update service, you do not have to set the RAB$L_ROP field RAB$V_TPT option to update data in the middle of a file.

For indexed files, the length of the replacement record written by the Update service may be different from the original record, but RMS does not permit you to change the primary key. Each replacement record must be large enough to contain a complete primary key, but it does not have to contain all alternate keys.

If an alternate key is partially or completely missing in the replacement record, the key must have the characteristic that the values can change; this is also true if the replacement record contains a key that was not present in the original record.

Update operations to an indexed file do not require a key value or key of reference. Before writing the record, RMS compares the key values (primary and alternate) in the replacement record with the key values of the original record already existing in the file. This comparison takes the defined characteristics of each key into account. For example, if a particular key is not allowed to change, RMS rejects the operation with an RMS$_CHG error code if the replacement record contains an altered value in the associated key. Similarly, this comparison determines whether the replacement record would result in the presence of duplicate key values among records of the file. If duplicates would occur, RMS verifies the defined characteristics for the keys being duplicated. If duplicates are not allowed for a particular key, RMS rejects the operation with an RMS$_DUP error code. If duplicates are allowed, RMS performs the operation.

Subsequent sequential operations on a given index retrieve records with identical key values in the order in which the records were written.

RAB Control Block Fields

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

Table RMS-95 Update Service RAB Input Fields

Field Name	Option	Description
RAB$W_ISI		Internal stream identifier (required).
RAB$L_RBF		Record buffer address.
RAB$L_RHB		Record header buffer (for variables with fixed control records only).
RAB$L_ROP		Record-processing options.
	RAB$V_ASY	Asynchronous: performs Update services asynchronously.
	RAB$V_WBH	Write-locked: two buffers are allocated to allow multibuffering.
RAB$W_RSZ		Record size (required).

Table RMS-96 lists the control block fields written as output by the Update service.

Table RMS-96 Update 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.

RAB64 Control Block Fields (Alpha Only)

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

Table RMS-97 Update 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_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.
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_RHB	Record header buffer. This field must contain -1 if you want to use RAB64$PQ_RHB. For 32-bit addressing, this field equates to RAB$L_RHB (see Table RMS-95).
RAB64$PQ_RHB	Record header buffer 64-bit address (used if RAB64$L_RHB 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-95. 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.
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.

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

Table RMS-98 Update 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-96).
RAB64$L_STV	Status value. Equates to RAB$L_STV.

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