Updated: 11 December 1998 |
OpenVMS Record Management Services Reference
Manual
Previous | Contents | Index |
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.
SYS$SPACE rab [,[err] [,suc]]
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.
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.
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).
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 |
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.
SYS$TRUNCATE rab [,[err] [,suc]]
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.
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.
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.
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 |
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.
SYS$UPDATE rab [,[err] [,suc]]
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.
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.
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.
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.
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. |
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 |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4523PRO_033.HTML
|