Document revision date: 15 July 2002
[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

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:

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. The maximum number of files that can be open within an image at one time is 16383.

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

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4523PRO_028.HTML