HP OpenVMS Systems Documentation

Content starts here

OpenVMS Record Management Services Reference Manual


Previous Contents Index


$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:

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

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    

$WAIT

The Wait service suspends image execution until an asynchronous file or record service completes. The same control block that is used with the asynchronous file or record service call is specified as the parameter for the Wait service. If it is an asynchronous file service, the control block is a FAB; if it is an asynchronous record service, the control block is a RAB. Upon completion of the service, RMS returns control to your program at the point following the Wait service call.

RAB64 Users (Alpha Only)

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

Format

SYS$WAIT control-block


RETURNS


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

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


Argument

control-block


type:
access:

fab or rab


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

FAB or RAB control block whose contents are to be used as indirect arguments for the Open service call. The fab or rab argument is the address of the FAB or RAB control block.

Description

The Wait service takes no arguments to define entry points for user-written completion routines; the completion routines are specified by the service being awaited.

Any completion routines specified on the operation being awaited are declared as ASTs before RMS returns control. They are executed before the Wait service completes unless ASTs are disabled. Completion routines are always executed as asynchronous system traps (ASTs).

Table RMS-99 lists the control block fields used as input by the Wait service for the FAB. For additional information on the fields accessed by this service, see Part 2 of this manual.

Table RMS-99 Wait Service FAB Input Fields
Field Name Description
FAB$W_IFI Internal file identifier (required).
FAB$L_STS Status completion code.

Table RMS-100 lists the control block field written as output by the Wait service for the FAB.

Table RMS-100 Wait Service FAB Output Field
Field Name Description
FAB$L_STS Completion status code (also returned in register 0).

Table RMS-101 lists the control block fields used as input by the Wait service for the RAB. For additional information on the fields accessed by this service, see Part 2 of this manual.

Table RMS-101 Wait Service RAB Input Fields
Field Name Description
RAB$W_ISI Internal stream identifier (required).
RAB$L_STS Status completion code.

Table RMS-102 lists the control block field written as output by the Wait service for the RAB.

Table RMS-102 Wait Service RAB Output Field
Field Name Description
RAB$L_STS Completion status code (also returned in register 0).

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$_BLN RMS$_CDA RMS$_EXT_ERR
RMS$_FAB RMS$_ISI RMS$_NORMAL
RMS$_OPNOTSUP RMS$_RAB RMS$_STR
RMS$_SUC    

The RMS completion status codes for the Wait service are determined by the service being awaited, unless the address of the FAB or RAB specified for the wait is different from that specified for the awaited operation. In this case, RMS$_NORMAL is returned.


Previous Next Contents Index