HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

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.

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

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.