OpenVMS Record Management Services Reference Manual

Document revision date: 15 July 2002

OpenVMS Record Management Services Reference Manual

Contents

Index

$DISCONNECT

The Disconnect service breaks the connection between a RAB and a FAB, thereby terminating a record stream. All system resources, such as I/O buffers and data structure space, are deallocated.

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

Format

SYS$DISCONNECT 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 Disconnect 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 Close service (see $CLOSE) performs an implied disconnect for all record streams connected to the FAB. Thus, you need not explicitly issue a Disconnect service prior to closing the file. However, if more than one RAB is connected to a single FAB, then you must explicitly disconnect the desired RAB in order to terminate a particular record stream and leave the others active.
Table RMS-13 lists the control block fields read as input by the Disconnect service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-13 Disconnect Service RAB Input Fields
Field Name Option Description

RAB$W_ISI Internal stream identifier (required).

RAB$L_ROP Record-processing option.

RAB$V_ASY Asynchronous. Performs Disconnect service asynchronously.

Table RMS-14 lists the control block fields written as output by the Disconnect service.

Table RMS-14 Disconnect Service RAB Output Fields
Field Name Description

RAB$W_ISI Internal stream identifier (zeroed).

RAB$L_STS Completion status code (also returned in register 0).

RAB$L_STV Status value.

**Table RMS-13 Disconnect Service RAB Input Fields**
Field Name	Option	Description
RAB$W_ISI		Internal stream identifier (required).
RAB$L_ROP		Record-processing option.
	RAB$V_ASY	Asynchronous. Performs Disconnect service asynchronously.

**Table RMS-14 Disconnect Service RAB Output Fields**
Field Name	Description
RAB$W_ISI	Internal stream identifier (zeroed).
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$_CRC	RMS$_DME	RMS$_DNR
RMS$_EXT_ERR	RMS$_ISI	RMS$_NET
RMS$_NETFAIL	RMS$_NORMAL	RMS$_OPNOTSUP
RMS$_PENDING	RMS$_RAB	RMS$_RSA
RMS$_STR	RMS$_SUC	RMS$_SUP
RMS$_SUPPORT	RMS$_SYS	RMS$_WBE
RMS$_WER	RMS$_WLK

$DISPLAY

The Display service retrieves file attribute information about a file and places this information in fields in the FAB, in XABs chained to the FAB, and in a NAM or NAML block (if one is requested).

Format

SYS$DISPLAY 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 Display 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

A file must be open for access by a Create or Open service before the Display service can be invoked.
RMS places the file attribute information in the corresponding fields of the FAB and specified XABs. If the FAB$L_NAM field contains a valid NAM or NAML block address, certain NAM or NAML block fields are filled in, including the resultant string, and the NAM$B_NOP options are examined.
Note that the Open and Create services automatically perform an implicit Display service (see $OPEN and $CREATE).
Table RMS-15 lists the FAB control block fields read as input by the Display service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-15 Display Service FAB Input Fields
Field Name Description

FAB$W_IFI Internal file identifier.

FAB$L_NAM ¹ NAM or NAML block address.

FAB$L_XAB ¹ Extended attribute block address.

**Table RMS-15 Display Service FAB Input Fields**
Field Name	Description
FAB$W_IFI	Internal file identifier.
FAB$L_NAM ¹	NAM or NAML block address.
FAB$L_XAB ¹	Extended attribute block address.

¹ If you want information about a particular XAB, NAM, or NAML block, you must pass it to the Display service as input.

Table RMS-16 lists the FAB and XAB control block fields written as output by the Display service.

Table RMS-16 Display Service FAB and XAB Output Fields
Field Name XAB Type Description

FAB$L_ALQ Allocation quantity in blocks.

FAB$B_BKS Bucket size.

FAB$W_BLS Block size.

FAB$W_DEQ Default file extension quantity.

FAB$L_DEV Device characteristics.

FAB$B_FAC File access.

FAB$B_FSZ Fixed control area size.

FAB$W_GBC Global buffer count.

FAB$L_MRN Maximum record number.

FAB$W_MRS Maximum record size.

FAB$B_ORG File organization.

FAB$B_RAT Record attributes.

FAB$B_RFM Record format.

FAB$B_RTV Retrieval window size.

FAB$B_SHR File sharing.

FAB$L_STS Completion status code (also returned in register 0).

FAB$L_STV Status value.

FAB$L_XAB Next XAB address.

XABALL Allocation XAB; see Chapter 9.

XABDAT Date and time XAB; see Chapter 10.

XABFHC File header characteristics XAB; see Chapter 11.

XABITM Item list XAB; see Chapter 12.

XABKEY Key definition XAB; see Chapter 14.

XABPRO Protection XAB; see Chapter 15.

XABRDT Revision date and time XAB; see Chapter 16.

XABSUM Summary XAB; see Chapter 18.

**Table RMS-16 Display Service FAB and XAB Output Fields**
Field Name	XAB Type	Description
FAB$L_ALQ		Allocation quantity in blocks.
FAB$B_BKS		Bucket size.
FAB$W_BLS		Block size.
FAB$W_DEQ		Default file extension quantity.
FAB$L_DEV		Device characteristics.
FAB$B_FAC		File access.
FAB$B_FSZ		Fixed control area size.
FAB$W_GBC		Global buffer count.
FAB$L_MRN		Maximum record number.
FAB$W_MRS		Maximum record size.
FAB$B_ORG		File organization.
FAB$B_RAT		Record attributes.
FAB$B_RFM		Record format.
FAB$B_RTV		Retrieval window size.
FAB$B_SHR		File sharing.
FAB$L_STS		Completion status code (also returned in register 0).
FAB$L_STV		Status value.
FAB$L_XAB		Next XAB address.
	XABALL	Allocation XAB; see Chapter 9.
	XABDAT	Date and time XAB; see Chapter 10.
	XABFHC	File header characteristics XAB; see Chapter 11.
	XABITM	Item list XAB; see Chapter 12.
	XABKEY	Key definition XAB; see Chapter 14.
	XABPRO	Protection XAB; see Chapter 15.
	XABRDT	Revision date and time XAB; see Chapter 16.
	XABSUM	Summary XAB; see Chapter 18.

¹Not supported for DECnet for OpenVMS operations.

Table RMS-17 lists the NAM control block fields read as input by the Display service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-17 Display Service NAM Input Fields
Field Name Option Description

NAM$B_NOP NAM block options.

NAM$V_PWD Password: indicates that a password contained in a DECnet for OpenVMS access control string, if present in a file specification, is to be left unaltered in the expanded and resultant strings (instead of being replaced by the word "password").

NAM$V_NOCONCEAL Do not conceal device name: indicates that when a concealed device logical name is present, the concealed device logical name is to be replaced by the actual physical device name (and directory, if present) in the resultant string.

**Table RMS-17 Display Service NAM Input Fields**
Field Name	Option	Description
NAM$B_NOP		NAM block options.
	NAM$V_PWD	Password: indicates that a password contained in a DECnet for OpenVMS access control string, if present in a file specification, is to be left unaltered in the expanded and resultant strings (instead of being replaced by the word "password").
	NAM$V_NOCONCEAL	Do not conceal device name: indicates that when a concealed device logical name is present, the concealed device logical name is to be replaced by the actual physical device name (and directory, if present) in the resultant string.

Table RMS-18 lists the NAM control block fields written as output by the Display service.

Table RMS-18 Display Service NAM Output Fields
Field Name Description

NAM$W_DID ¹ Directory identification.

NAM$T_DVI ¹ Device identification.

NAM$W_FID ¹ File identification.

NAM$L_FNB File name status bits.

NAM$B_RSL Resultant string length: indicates the length of the resultant string that is written into the buffer whose address is contained in the NAM$L_RSA field (if the NAM$L_RSA and NAM$B_RSS fields are nonzero).

**Table RMS-18 Display Service NAM Output Fields**
Field Name	Description
NAM$W_DID ¹	Directory identification.
NAM$T_DVI ¹	Device identification.
NAM$W_FID ¹	File identification.
NAM$L_FNB	File name status bits.
NAM$B_RSL	Resultant string length: indicates the length of the resultant string that is written into the buffer whose address is contained in the NAM$L_RSA field (if the NAM$L_RSA and NAM$B_RSS fields are nonzero).

¹This field is not supported for DECnet for OpenVMS operations.
¹This field is not supported for DECnet for OpenVMS operations.

Table RMS-19 lists the NAML block fields used as input for the Display service.

Table RMS-19 Display Service NAML Input Fields (Alpha Only)
Field Name Option Description

NAML$L_INPUT_FLAGS Additional flags specified as input.

NAML$B_NOP NAML block options.

NAML$V_PWD Password: indicates that a password contained in a DECnet for OpenVMS access control string, if present in a file specification, is to be left unaltered in the expanded and resultant strings (instead of being replaced by the word "password").

NAML$V_NOCONCEAL Do not conceal device name: indicates that when a concealed device logical name is present, the concealed device logical name is to be replaced by the actual physical device name (and directory, if present) in the resultant string.

**Table RMS-19 Display Service NAML Input Fields (Alpha Only)**
Field Name	Option	Description
NAML$L_INPUT_FLAGS		Additional flags specified as input.
NAML$B_NOP		NAML block options.
	NAML$V_PWD	Password: indicates that a password contained in a DECnet for OpenVMS access control string, if present in a file specification, is to be left unaltered in the expanded and resultant strings (instead of being replaced by the word "password").
	NAML$V_NOCONCEAL	Do not conceal device name: indicates that when a concealed device logical name is present, the concealed device logical name is to be replaced by the actual physical device name (and directory, if present) in the resultant string.

¹This field is not supported for DECnet for OpenVMS operations.

Table RMS-20 lists the NAML block fields used as output for the Display service.

Table RMS-20 Display Service NAML Output Fields (Alpha Only)
Field Name Description

NAML$W_DID ¹ Directory identification.

NAML$T_DVI ¹ Device identification.

NAML$W_FID ¹ File identification.

NAML$L_FNB File name status bits.

NAML$L_LONG_RESULT_SIZE Long resultant string length.

NAML$L_OUTPUT_FLAGS Additional status bits passed as output.

NAML$B_RSL Resultant string length: indicates the length of the resultant string that is written into the buffer whose address is contained in the NAM$L_RSA field (if the NAML$L_RSA and NAML$B_RSS fields are nonzero).

**Table RMS-20 Display Service NAML Output Fields (Alpha Only)**
Field Name	Description
NAML$W_DID ¹	Directory identification.
NAML$T_DVI ¹	Device identification.
NAML$W_FID ¹	File identification.
NAML$L_FNB	File name status bits.
NAML$L_LONG_RESULT_SIZE	Long resultant string length.
NAML$L_OUTPUT_FLAGS	Additional status bits passed as output.
NAML$B_RSL	Resultant string length: indicates the length of the resultant string that is written into the buffer whose address is contained in the NAM$L_RSA field (if the NAML$L_RSA and NAML$B_RSS fields are nonzero).

¹This field is not supported for DECnet for OpenVMS operations.

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$_AID	RMS$_ATR
RMS$_BLN	RMS$_BUG_DAP	RMS$_CDA
RMS$_COD	RMS$_DME	RMS$_DNR
RMS$_ESA	RMS$_ESL	RMS$_ESS
RMS$_NAMLESS	RMS$_NAMLFSINV	RMS$_NAMLFSSIZ
RMS$_FAB	RMS$_IFI	RMS$_IMX
RMS$_NET	RMS$_NETFAIL	RMS$_NORMAL
RMS$_OK_NOP	RMS$_PLG	RMS$_PRV
RMS$_REF	RMS$_RPL	RMS$_STR
RMS$_SUC	RMS$_SUP	RMS$_SUPPORT
RMS$_XAB

$ENTER

The Enter service inserts a file name in a directory.

Note
The $ENTER service is not supported for DECnet.

Format

SYS$ENTER 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 Enter 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

The Enter service function is performed automatically by the Create service unless you select the FAB$V_TMP option or the FAB$V_TMD option. The Enter service, however, allows you to perform this step separately. Note that the file must be closed before you invoke the Enter service (FAB$W_IFI must be 0).
When you enter a file name in a directory, no file associated with the FAB can be open and no wildcard characters can be used.
The Enter service requires many NAM or NAML block fields as input. You normally precede the Enter service with an Open, Create, or Parse service (see $PARSE) and a Search service (see $SEARCH), specifying the same FAB and NAM block for each service.
The optional resultant string is moved to the buffer described by the NAM$L_RSA (or NAML$L_LONG_RESULT) and NAM$B_RSS (or NAML$L_LONG_RESULT_ALLOC) fields (only if both these fields are nonzero). If the file version number of the name string described by the expanded string length and address fields of the NAM or NAML block is omitted or contains a 0, the Enter service scans the entire directory. It assigns a version number that is one higher than the highest found (or 1 if none is found).

Note
The Enter service is not supported for DECnet for OpenVMS operations on remote files between two OpenVMS systems.

Table RMS-21 lists the FAB control block fields read as input by the Enter service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-21 Enter Service FAB Input Fields
Field Name Description

FAB$W_IFI Internal file identifier (must be 0).

FAB$L_NAM NAM or NAML block address.

Table RMS-22 lists the FAB control block fields read as output by the Enter service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-22 Enter Service FAB Output Fields
Field Name Description

FAB$L_STS Completion status code (also returned in register 0).

FAB$L_STV Status value.

Table RMS-23 lists the NAM control block fields read as input by the Enter service. For additional information on the fields accessed by this service, see Part 2.

Table RMS-23 Enter Service NAM Input Fields
Field Name Description

NAM$W_DID Directory identification: identifies the directory in which the file name is to be entered.

NAM$T_DVI Device identification: identifies the device containing the directory in which the file name is to be entered.

NAM$L_ESA Expanded string area address: contains file name, type, and version to be entered.

NAM$B_ESL Expanded string length.

NAM$W_FID File identification: identifies the file to be entered into the directory.

NAM$L_RSA Resultant string area address.

NAM$B_RSS Resultant string size.

Previous Next Contents Index

privacy and legal statement

4523PRO_024.HTML

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

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

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

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

Field Name	Description
FAB$W_IFI	Internal file identifier (must be 0).
FAB$L_NAM	NAM or NAML block address.

Field Name	Description
NAM$W_DID	Directory identification: identifies the directory in which the file name is to be entered.
NAM$T_DVI	Device identification: identifies the device containing the directory in which the file name is to be entered.
NAM$L_ESA	Expanded string area address: contains file name, type, and version to be entered.
NAM$B_ESL	Expanded string length.
NAM$W_FID	File identification: identifies the file to be entered into the directory.
NAM$L_RSA	Resultant string area address.
NAM$B_RSS	Resultant string size.