Document revision date: 19 July 1999
[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


$SPACE

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.

RMS$_ACT RMS$_BLN RMS$_BOF
RMS$_BUG_DAP RMS$_CDA RMS$_DME
RMS$_DNR RMS$_DPE RMS$_EOF
RMS$_IOP RMS$_ISI RMS$_NET
RMS$_NETFAIL RMS$_NORMAL RMS$_PENDING
RMS$_RAB RMS$_RSA RMS$_STR
RMS$_SUC RMS$_SUP RMS$_SUPPORT
RMS$_SYS RMS$_WBE  

$TRUNCATE

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:

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.

RMS$_ACT RMS$_ATR RMS$_ATW
RMS$_BLN RMS$_BUG_DAP RMS$_CDA
RMS$_CUR RMS$_DEADLOCK RMS$_DME
RMS$_DNR RMS$_DPE RMS$_EXT_ERR
RMS$_FAC RMS$_IOP RMS$_ISI
RMS$_NET RMS$_NETFAIL RMS$_NORMAL
RMS$_OPNOTSUP RMS$_PENDING RMS$_RAB
RMS$_RER RMS$_RSA RMS$_STR
RMS$_SUC RMS$_SUP RMS$_SUPPORT
RMS$_SYS RMS$_WBE RMS$_WER
RMS$_WLK    

$UPDATE

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.


1One of the RBF fields must contain an address and the RSZ field associated with it must contain a size.

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.

RMS$_ACT RMS$_ATR RMS$_ATW
RMS$_BLN RMS$_BUG RMS$_BUG_DAP
RMS$_CDA RMS$_CHG RMS$_CHK
RMS$_CUR RMS$_DME RMS$_DNR
RMS$_DUP RMS$_ENQ RMS$_EXP
RMS$_EXT_ERR RMS$_FAC RMS$_FTM
RMS$_IBF RMS$_IDX RMS$_IOP
RMS$_NETBTS RMS$_NETFAIL RMS$_NORMAL
RMS$_OK_DUP RMS$_OK_IDX RMS$_OPNOTSUP
RMS$_PENDING RMS$_PLG RMS$_RAB
RMS$_RBF RMS$_RER RMS$_RHB
RMS$_RNL RMS$_RPL RMS$_RRV
RMS$_RSA RMS$_RSZ RMS$_RVU
RMS$_STR RMS$_SUC RMS$_SUP
RMS$_SUPPORT RMS$_SYS RMS$_TRE
RMS$_WBE RMS$_WER RMS$_WLK
RMS$_WPL    


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