Document revision date: 30 March 2001

## OpenVMS Record Management Services Reference Manual

Previous | Contents | Index

Table RMS-44 lists the RAB control block fields written as output by the Get service.

Table RMS-44 Get Service RAB Output Fields
Field Name | Description
--- | ---
RAB$L_BKT | Bucket code: set to the relative record number for relative files when the record access mode is sequential.
RAB$L_RBF | Record buffer address.
RAB$W_RFA | Record file address.
RAB$W_RSZ | Record size.
RAB$L_STS | Completion status code (also returned in register 0).
RAB$L_STV | Status value (contains a terminator character for terminal input or the record length if the requested record is too large for the user buffer area).

RAB64 Control Block Fields (Alpha Only)

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

Table RMS-45 Get 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_KBF | Key buffer address. This field must contain -1 if you want to use RAB64$PQ_KBF. For 32-bit addressing, this field equates to RAB$L_KBF (see Table RMS-43).
RAB64$PQ_KBF | Key buffer 64-bit address (used if RAB64$L_KBF contains -1 ). This field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.
RAB64$B_KRF | Key of reference. Equates to RAB$B_KRF (see Table RMS-43).
RAB64$B_KSZ | Key buffer size. Equates to RAB$B_KSZ (see Table RMS-43).
RAB64$L_PBF 1 | Prompt buffer address. Equates to RAB$L_PBF (see Table RMS-43).
RAB64$B_PSZ 1 | Prompt buffer size. Equates to RAB$B_PSZ (see Table RMS-43).
RAB64$B_RAC | Record access mode. Equates to RAB$B_RAC and constants described in Table RMS-43. The constants are identical except for the RAB64 prefix; for example, RAB64$C_KEY equates to RAB$C_KEY.
RAB64$W_RFA | Record file address. Equates to RAB$W_RFA (see Table RMS-43).
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-43).
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-43. Options are identical except for the RAB64 prefix; for example, option RAB64$V_ASY equates to RAB$V_ASY.
RAB64$W_ROP_2 1 | Extended record-processing options. Equates to RAB$W_ROP_2 and options described in Table RMS-43. Options are identical except for the RAB64 prefix; for example, option RAB64$V_NODLCKWT equates to RAB$V_NODLCKWT.
RAB64$B_TMO 1 | Timeout period. Equates to RAB$B_TMO (see Table RMS-43).
RAB64$L_UBF 2 | User record buffer address. This field must contain -1 if you want to use RAB64$PQ_UBF. For 32-bit addressing, this field equates to RAB$L_UBF (see Table RMS-43).
RAB64$PQ_UBF 2 | User record buffer 64-bit address (used if RAB64$L_UBF contains -1 ). This field can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits.
RAB64$W_USZ 2 | User record buffer size. This field is ignored in favor of RAB64$Q_USZ if RAB64$L_UBF contains -1 . Otherwise, this field equates to RAB$W_USZ (see Table RMS-43).
RAB64$Q_USZ 2 | User record buffer size. This field must be used when RAB64$L_UBF contains -1 and a value is specified in RAB64$PQ_UBF.
RAB64$L_XAB | Next XAB address. Equates to RAB$L_XAB and its XABTRM option (see Table RMS-43).

1This field is not supported for DECnet for OpenVMS operations.
2One of the UBF fields must contain an address and the USZ field associated with it must contain a size.

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

Table RMS-46 Get Service RAB64 Output Fields (Alpha Only)
Field Name | Description
--- | ---
RAB64$L_BKT | Bucket code. Equates to RAB$L_BKT (see Table RMS-44).
RAB64$L_RBF | Record buffer address is returned to this field if RAB64$L_UBF does not contain -1 . Equates to RAB$L_RBF.
RAB64$PQ_RBF | Record buffer address is returned to this field if RAB64$L_UBF contains -1 .
RAB64$W_RFA | Record file address. Equates to RAB$W_RFA.
RAB64$W_RSZ | Record buffer size is returned to this field if RAB64$L_UBF does not contain -1 . Equates to RAB$W_RSZ.
RAB64$Q_RSZ | Record buffer size is returned to this field if RAB64$L_UBF contains -1 .
RAB64$L_STS | Completion status code. Equates to RAB$L_STS (see Table RMS-44).
RAB64$L_STV | Status value. Equates to RAB$L_STV (see Table RMS-44).

### 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$_ANI | RMS$_BES
RMS$_BLN | RMS$_BUG | RMS$_BUG_DAP
RMS$_CDA | RMS$_CHK | RMS$_CONTROLC
RMS$_CONTROLY | RMS$_DEADLOCK | RMS$_DEL
RMS$_DME | RMS$_DNR | RMS$_EOF
RMS$_ENQ | RMS$_EXENQLM | RMS$_EXP
RMS$_EXT_ERR | RMS$_FAC | RMS$_FTM
RMS$_IBF | RMS$_IDXSEARCH | RMS$_IOP
RMS$_IRC | RMS$_ISI | RMS$_KBF
RMS$_KEY | RMS$_KRF | RMS$_KSZ
RMS$_MRN | RMS$_NET | RMS$_NETBTS
RMS$_NETFAIL | RMS$_NORMAL | RMS$_OK_ALK
RMS$_OK_DEL | RMS$_OK_LIM | RMS$_OK_RLK
RMS$_OK_RNF | RMS$_OK_RRL | RMS$_OK_WAT
RMS$_OPNOTSUP | RMS$_PBF | RMS$_PENDING
RMS$_PES | RMS$_PLG | RMS$_RAB
RMS$_RAC | RMS$_RER | RMS$_RFA
RMS$_RHB | RMS$_RLK | RMS$_RNF
RMS$_ROP | RMS$_RPL | RMS$_RRV
RMS$_RSA | RMS$_RTB | RMS$_SQO
RMS$_STR | RMS$_SUC | RMS$_SUP
RMS$_SUPPORT | RMS$_SYS | RMS$_TMO
RMS$_TNS | RMS$_TRE | RMS$_UBF
RMS$_WBE | RMS$_WER | RMS$_WLK
RMS$_XAB |  |

## $NXTVOL

> The Next Volume service allows you to process the next tape volume in a multiple volume set. This service applies only to files on magnetic tape volumes.

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

### Format

> SYS$NXTVOL 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 Next Volume 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

> You use the Next Volume service when you want to proceed to the next volume in the set before the end of the current volume (EOV label) is reached on input, or before the end-of-tape (EOT) mark is reached on output. RMS positions your process to the first file section on the next volume. File sections occur when a file is written on more than one volume, the portion of the file on each of the volumes constituting a file section.

> When you perform a Next Volume service for input files, RMS responds as follows:

> - If the current volume is the last volume of the set, RMS reports end-of-file information.
> - If another file section exists, the next volume is mounted. When necessary, the current volume is rewound and a request to mount the next volume is issued to the operator.
> - The header label (HDR1) of the file section on the newly mounted volume is read. If this is not the volume being sought, the operator is requested to mount the correct volume.

> When you perform a Next Volume service for output files, the following sequence occurs:

> 1. The file section on the current volume is closed with the appropriate end-of-volume labels, and the volume is rewound.
> 2. The next volume is mounted.
> 3. A file with the same file name and the next higher file section number is opened for output, and processing continues.

> If your program is operating asynchronously, it must wait for any I/O activity on this volume to complete before issuing a Next Volume service.

> The Next Volume service performs a Flush service for write-accessed volumes (see $FLUSH), thus writing the I/O buffers on the current volume before creating the next file section. If this is an input-only file, then all records currently contained in the I/O buffers are lost, and the next Get service returns the first record on the next volume.

> The Next Volume service is not supported for DECnet for OpenVMS operations on files between two OpenVMS systems.

> Table RMS-47 lists the control block fields read as input and written as output by the Next Volume service. For additional information on the fields accessed by this service, see Part 2.

> Table RMS-47 Next Volume 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 Next Volume service asynchronously.

> Table RMS-48 lists the control block fields written as output by the Next Volume service.

> Table RMS-48 Delete 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$_BLN | RMS$_CDA
RMS$_DME | RMS$_DNR | RMS$_DPE
RMS$_EXT_ERR | RMS$_IOP | RMS$_ISI
RMS$_NORMAL | RMS$_OPNOTSUP | RMS$_PENDING
RMS$_RAB | RMS$_RSA | RMS$_STR
RMS$_SUC | RMS$_SUP | RMS$_SUPPORT
RMS$_SYS |  |

## $OPEN

> The Open service makes an existing file available for processing by your program. The Open service specifies the type of record access to be used and determines whether the file can be shared. The Open service also performs an implicit Display service.

### Format

> SYS$OPEN fab [,[err] [,suc]]

### RETURNS

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

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

### Arguments

> #### fab

> OpenVMS usage: | fab
> type: | longword (unsigned)
> access: | modify
> mechanism: | by reference

> FAB control block whose contents are to be used as indirect arguments for the Open service call. The fab argument is the address of the FAB 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

> You must open a file to perform any record operations and most file operations. If any XABs are chained to the FAB, RMS places the attribute values in the fields of the appropriate XAB. If you specify a NAM or NAML block in the FAB, the contents of the device, directory, and file identification fields can be used with the open-by-NAM-block option to open the file. The NAM or NAML block fields are filled in with auxiliary file specification information.

> Table RMS-49 lists the FAB and XAB control block fields read as input by the Open service. For additional information on the fields accessed by this service, see Part 2.

> Table RMS-49 Open Service FAB and XAB Input Fields
> Field Name | Option or XAB Type | Description
> --- | --- | ---
> FAB$B_ACMODES |  | File access modes.
> | FAB$V_CHAN_MODE 1 | Assigns the channel access mode by setting either the FAB$V_UFO or the FAB$V_NFS bit in the FAB$L_FOP field (see Section 4.17). If neither bit is set, this field can be used to override the access mode protection for a specified I/O operation. See Section 4.8.
> | FAB$V_LNM_MODE 1 | Specifies the logical name translation access mode.
> FAB$W_DEQ |  | Default file extension quantity: if a nonzero value is present in this field, it applies only to this open of the file.
> FAB$L_DNA |  | Default file specification string address.
> FAB$B_DNS |  | Default file specification string size.
> FAB$B_FAC |  | File access field.
> | FAB$V_BIO | Block I/O access.
> | FAB$V_BRO | Block or record I/O.
> | FAB$V_DEL | Delete access.
> | FAB$V_GET 2 | Read access.
> | FAB$V_PUT | Write access.
> | FAB$V_TRN | Truncate access.
> | FAB$V_UPD | Update access.
> FAB$L_FNA 3 |  | File specification string address.
> FAB$B_FNS 3 |  | File specification string size.
> FAB$L_FOP |  | File-processing options.
> | FAB$V_ASY | Asynchronous; indicates that the specified task is to be done asynchronously.
> | FAB$V_DFW 1 | Deferred write: indicates that writing back to the file from the modified buffer is deferred (applies to relative and indexed files only).
> | FAB$V_DLT | Delete: indicates the file is to be deleted when it is closed.
> | FAB$V_NAM 1 | Name block inputs: indicates that the NAM$W_FID, NAM$W_DID, and NAM$T_DVI fields in the specified NAM or NAML block are to be used to describe the file.
> | FAB$V_NFS 1 | Non-file-structured: indicates that the accessed volume is to be processed in a non-file-structured manner.
> | FAB$V_OFP | Output file parse: specifies that the related file resultant file specification string, if used, is to provide file name and file type defaults only.
> | FAB$V_RCK | Read-check: indicates that transfers from disk are to be checked by a followup, read-compare operation.
> | FAB$V_RWC | Rewind on close (applies to magnetic tapes only).
> | FAB$V_RWO | Rewind on open (applies to magnetic tapes only).
> | FAB$V_SCF 1 | Submit command file: indicates that the file is to be submitted as a batch-command file to the process default batch queue (SYS$BATCH) when the file is closed (applies to sequential files only).
> | FAB$V_SPL 1 | Spool: indicates that the file is to be spooled to the process default print queue (SYS$PRINT) when the file is closed (applies to sequential files only).
> | FAB$V_SQO | Sequential only: indicates that the file can be processed in a sequential manner only.
> | FAB$V_TEF | Truncate at end of file: indicates that unused space allocated to a file is to be deallocated when that file is closed (applies to sequential files only).
> | FAB$V_UFO 1 | User file open: indicates the file is to be opened only (no further processing of that file is allowed).
> | FAB$V_WCK | Write-check: indicates that transfers to disk are to be followed by a read-compare operation.
> FAB$B_FSZ |  | Fixed control area size: unit record devices only.
> FAB$W_IFI |  | Internal file identifier (must be 0).
> FAB$L_NAM |  | NAM or NAML block address.
> FAB$B_RAT |  | Record attributes; only for process permanent files with print file format.
> FAB$B_RFM |  | Record format; unit record devices only.
> FAB$B_RTV 1 |  | Retrieval window size.
> FAB$B_SHR |  | File-sharing field.
> | FAB$V_SHRDEL | Shared delete access.
> | FAB$V_SHRGET | Shared read access.
> | FAB$V_MSE 1 | Multistream access; also used with the FAB$V_MSE and FAB$V_GET bits to specify a read-only global buffer cache when global buffering is enabled.
> | FAB$V_NIL | No shared access.
> | FAB$V_SHRPUT | Shared write access.
> | FAB$V_SHRUPD | Shared update access.
> | FAB$V_UPI | Shared write access for block I/O (applies to sequential files only).
> | FAB$V_NQL | No query record locking.
> FAB$L_XAB 4 |  | Extended attribute block address.
> | XABITM | Item list XAB; see Chapter 12.

1This field is not supported for DECnet for OpenVMS operations.
2This is the default value supplied by RMS.
3These fields must be supplied by the user.
4The appropriate XAB must be specified as input if you desire information about that particular XAB on output from the Open service.

Previous | Next | Contents | Index

| privacy and legal statement |
4523PRO_027.HTML