Document revision date: 19 July 1999

The Rewind service sets the context of a record stream to the first record in the file. RMS alters the context of the next record to indicate the first record as being the next record.

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

Format

SYS$REWIND 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 Rewind 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 Rewind service implicitly performs the Flush and Free services, writing out all I/O buffers and releasing all locked records. This service is valid for all file organizations on disk volumes and for sequential files on tape volumes. For indexed files, the key of reference field establishes the index to be used for subsequent sequential accesses. You cannot rewind a unit record device (such as a card reader), indirectly accessed process-permanent files, or a file that was opened with the FAB$V_SQO option set.

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

Table RMS-83 Rewind Service RAB Input Fields

Field Name	Option	Description
RAB$W_ISI		Internal stream identifier (required).
RAB$B_KRF		Key of reference (used only with indexed files).
RAB$L_ROP		Record-processing options.
	RAB$V_ASY	Asynchronous: performs Rewind service asynchronously.

Table RMS-84 lists the control block fields written as output by the Rewind service.

Table RMS-84 Rewind 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 Search service scans a directory file and fills in various NAM or NAML block fields. This service should be preceded by the Parse service, in order to initialize the NAM or NAML block appropriately.

Format

SYS$SEARCH 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 Search 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 basic functions of the Search service and the Parse service are performed automatically as part of the Open, Create, and Erase services. Note that you must close the file before invoking the Search service (FAB$W_IFI must be 0).

When called, the Search service scans the directory file specified by the directory identification (NAM$W_DID or NAML$W_DID) field of the NAM or NAML block. It looks for an entry that matches the file name, type, and version number specified by the expanded string area address and expanded string length fields. Upon finding a match, RMS returns the file name, type, and version number in the buffer described by the resultant string area address and size fields. RMS also fills in the file identification field to enable a subsequent open-by-NAM-block operation. You can also use the Search service to obtain a series of file specifications whose names match a file specification that contains wildcard characters or search lists.

The resultant file specification string is placed in the buffer described by NAM$L_RSA (or NAML$L_LONG_RESULT) and NAM$B_RSS (or NAML$L_LONG_RESULT_ALLOC) fields of the NAM or NAML block (only if both fields are nonzero). The NAM$L_RSA and NAM$B_RSS fields must be specified (nonzero) for wildcard character processing.

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

Table RMS-85 Search Service FAB Input Fields

Field Name	Option	Description
FAB$B_ACMODES		File access modes.
	FAB$V_CHAN_MODE 1	This field can be used to override the access mode protection for a specified I/O operation (see Section 4.8).
FAB$W_IFI		Internal file identifier (must be zero).
FAB$L_NAM		NAM or NAML block address.

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

Table RMS-86 Search Service FAB Block Output Fields

Field Name	Description
FAB$L_STS	Completion status code (also returned in register 0).
FAB$L_STV	Status value.

Table RMS-87 lists the NAM control block fields read as input by the Search service.

Table RMS-87 Search Service NAM Input Fields

Field Name	Option	Description
NAM$W_DID 1		Directory identification of the directory to be searched.
NAM$T_DVI 1		Device identification of device containing directory to be searched.
NAM$L_ESA		Expanded string area address: specifies file name, type, and version of file.
NAM$B_ESL		Expanded string length.
NAM$L_FNB		File name status bits (wildcard character options only).
NAM$B_NOP		NAM block options.
	NAM$V_NO_SHORT_UPCASE 1	Do not uppercase the directory and file specification in the NAM$L_ESA buffer.
	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 in the resultant string.
	NAM$V_SRCHXABS	Performs Display service on remote files (for output fields, see description of Display service).
NAM$L_RSA		Resultant string area address: specifies name, type, and version of last file found (required for wildcard character processing).
NAM$B_RSL		Resultant string length.
NAM$B_RSS		Resultant string area size.
NAM$L_WCC		Wildcard character context value.

Table RMS-88 lists the NAM control block fields written as output by the Search service.

Table RMS-88 Search Service NAM Output Fields

Field Name	Description
NAM$L_DEV	Address of file specification device string.
NAM$B_DEV	Size of file specification device string.
NAM$L_DIR	Address of file specification directory string.
NAM$B_DIR	Size of file specification directory string.
NAM$W_FID 1	File identification.
NAM$W_FIRST_WILD_DIR 1	First wild directory.
NAM$L_FNB	File name status bits (wildcard status bits only).
NAM$W_LONG_DIR_LEVELS 1	Total number of directories.
NAM$L_NAME	Address of file specification name string.
NAM$B_NAME	Size of file specification name string.
NAM$L_NODE	Address of file specification node string.
NAM$B_NODE	Size of file specification node string.
NAM$B_RSL	Resultant string length.
NAM$L_TYPE	Address of file specification type string.
NAM$B_TYPE	Size of file specification type string.
NAM$L_VER	Address of file specification version string.
NAM$B_VER	Size of file specification version string.
NAM$L_WCC	Wildcard character context value.

Table RMS-89 lists the NAML control block fields written as input by the Search service.

Table RMS-89 Search Service NAML Input Fields (Alpha Only)

Field Name	Option	Description
NAML$W_DID 1		Directory identification of the directory to be searched.
NAML$T_DVI 1		Device identification of device containing directory to be searched.
NAML$L_ESA		Expanded string area address: specifies file name, type, and version of file.
NAML$B_ESL		Expanded string length.
NAML$L_FNB		File name status bits (wildcard character options only).
NAML$L_FILESYS_NAME 1		File system name buffer address.
NAML$L_FILESYS_NAME_ALLOC 1		File system name buffer size.
NAML$L_INPUT_FLAGS 1		Additional flags specified as input.
NAML$L_LONG_EXPAND 1		Long expanded string area address.
NAML$L_LONG_EXPAND_ALLOC 1		Long expanded string area size.
NAML$L_LONG_RESULT		Long resultant string area address.
NAML$L_LONG_RESULT_ALLOC 1		Long resultant string area size.
NAML$B_NOP		NAML block options.
	NAML$V_NO_SHORT_UPCASE 1	Do not uppercase the directory and file specification in the NAML$L_ESA buffer.
	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 in the resultant string.
	NAML$V_SRCHXABS	Performs Display service on remote files (for output fields, see description of Display service).
NAML$L_RSA		Resultant string area address: specifies name, type, and version of last file found (required for wildcard character processing).
NAML$B_RSL		Resultant string length.
NAML$B_RSS		Resultant string area size.
NAML$L_WCC		Wildcard character context value.

Table RMS-90 lists the NAML control block fields read as output by the Search service.

Table RMS-90 Search Service NAML Output Fields (Alpha Only)

Field Name	Description
NAML$L_DEV	Address of file specification device string.
NAML$B_DEV	Size of file specification device string.
NAML$L_DIR	Address of file specification directory string.
NAML$B_DIR	Size of file specification directory string.
NAML$W_FID 1	File identification.
NAML$W_FIRST_WILD_DIR 1	First wild directory.
NAML$L_FNB	File name status bits (wildcard status bits only).
NAML$L_FILESYS_NAME_SIZE 1	File system name length.
NAML$L_LONG_DEV 1	Long device string address.
NAML$L_LONG_DEV_SIZE 1	Long device string length.
NAML$L_LONG_DIR 1	Long directory string address.
NAML$W_LONG_DIR_LEVELS 1	Total number of directories.
NAML$L_LONG_DIR_SIZE 1	Long directory string length.
NAML$L_LONG_NAME 1	Long file name string address.
NAML$L_LONG_NAME_SIZE 1	Long file name string length.
NAML$L_LONG_NODE 1	Long node name string address.
NAML$L_LONG_NODE_SIZE 1	Long node name string length.
NAML$L_LONG_RESULT_SIZE 1	Long resultant string length.
NAML$L_LONG_TYPE 1	Long file type string length.
NAML$L_LONG_TYPE_SIZE 1	Long file type string address.
NAML$L_LONG_VER 1	Long file version string address.
NAML$L_LONG_VER_SIZE 1	Long file version string length.
NAML$L_NAME	Address of file specification name string.
NAML$B_NAME	Size of file specification name string.
NAML$L_NODE	Address of file specification node string.
NAML$B_NODE	Size of file specification node string.
NAML$L_OUTPUT_FLAGS 1	Additional status bits passed as output.
NAML$B_RSL	Resultant string length.
NAML$L_TYPE	Address of file specification type string.
NAML$B_TYPE	Size of file specification type string.
NAML$L_VER	Address of file specification version string.
NAML$B_VER	Size of file specification version string.
NAML$L_WCC	Wildcard character context 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.

	privacy and legal statement
4523PRO_032.HTML