HP OpenVMS Systems Documentation

Content starts here

OpenVMS Record Management Services Reference Manual


Previous Contents Index


$SEARCH

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.

1This field or option is not supported for DECnet for OpenVMS operations.

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.

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

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.

1This field or option is not supported for DECnet for OpenVMS operations.

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.

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

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   Additional flags specified as input.
NAML$L_LONG_EXPAND   Long expanded string area address.
NAML$L_LONG_EXPAND_ALLOC   Long expanded string area size.
NAML$L_LONG_RESULT   Long resultant string area address.
NAML$L_LONG_RESULT_ALLOC   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.

1This field or option is not supported for DECnet for OpenVMS operations.

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 Long device string address.
NAML$L_LONG_DEV_SIZE Long device string length.
NAML$L_LONG_DIR Long directory string address.
NAML$W_LONG_DIR_LEVELS 1 Total number of directories.
NAML$L_LONG_DIR_SIZE Long directory string length.
NAML$L_LONG_NAME Long file name string address.
NAML$L_LONG_NAME_SIZE Long file name string length.
NAML$L_LONG_NODE Long node name string address.
NAML$L_LONG_NODE_SIZE Long node name string length.
NAML$L_LONG_RESULT_SIZE Long resultant string length.
NAML$L_LONG_TYPE Long file type string length.
NAML$L_LONG_TYPE_SIZE Long file type string address.
NAML$L_LONG_VER Long file version string address.
NAML$L_LONG_VER_SIZE 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 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.

1This 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$_ACS RMS$_BLN RMS$_CHN
RMS$_DEV RMS$_DME RMS$_DNF
RMS$_DNR RMS$_DVI RMS$_ESA
RMS$_ESL RMS$_FAB RMS$_FND
RMS$_FNF RMS$_IFI RMS$_NAM
RMS$_NAML RMS$_NAMLFSINV RMS$_NAMLFSSIZ
RMS$_NAMLRSS RMS$_NET RMS$_NETFAIL
RMS$_NMF RMS$_NORMAL RMS$_NOVALPRS
RMS$_PRV RMS$_RSL RMS$_RSS
RMS$_RST RMS$_STR RMS$_SUC
RMS$_SUP RMS$_SUPPORT RMS$_SYS
RMS$_WCC    

$SPACE

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.

Format

SYS$SPACE 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 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.

Description

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).

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$_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  


Previous Next Contents Index