 |
OpenVMS Record Management Services Reference
Manual
$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.
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
|
|
|
