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


$PARSE

The Parse service analyzes the file specification string and fills in various NAM or NAML block fields.

Format

SYS$PARSE 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 Parse 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 functions of the Parse service are performed automatically as part of the Open, Create, and Erase services. One special purpose of the Parse service is to prepare the FAB and NAM or NAML blocks for wildcard character processing to be used in the Search service. If wildcard characters, search list logical names, or a node name are present in the file specification, RMS allocates internal data structures (including a device channel) to store the context for subsequent searches. This space is released when the Search service encounters a no-more-files condition (in which case an RMS$_NMF error status is returned) or when another Parse service is performed using the same FAB and NAM or NAML blocks. To release this space, use a Parse service that specifies the NAM$B_NOP field NAM$V_SYNCHK option and sets the FAB$B_DNS and NAM$L_RLF fields to zero. If you are using the NAML$L_LONG_DEFNAME and NAM$L_LONG_DEFNAME_SIZE fields, set the NAML$L_LONG_DEFNAME_SIZE field to zero in place of FAB$B_DNS.

Note that the file must be closed before you invoke the Parse service (FAB$W_IFI must be 0).

By default, the Parse service assigns a channel to the device and does a lookup of the directory in addition to analyzing the file specification and filling in the NAM or NAML block fields. To request a Parse service without I/O, specify the NAM$B_NOP field NAM$V_SYNCHK option. The result of a Parse service without I/O cannot be used as input to subsequent Search services.

The following tables list the fields in both the FAB and NAM or NAML blocks that the Parse service uses as input and output. In addition, RMS fills in the string component descriptors from the expanded string (see Chapter 5).

The expanded file specification string is moved to the buffer described by the expanded string area address (NAM$L_ESA) and size (NAM$B_ESS) fields of the NAM or NAML block (only if both fields are nonzero). The NAM$L_ESA and NAM$B_ESS fields must be specified (nonzero) for wildcard character processing.

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

Table RMS-55 Parse 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$L_DNA   Default file specification string.
FAB$B_DNS   Default file specification string size.
FAB$L_FNA   File specification string address.
FAB$B_FNS   File specification string size.
FAB$L_FOP   File-processing option, FAB$V_OFP. Output file parse: indicates that RMS uses only the file name and file type fields of a related file resultant string whose address is contained in the NAM$L_RSA field.
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-56 lists the FAB control block fields written as output by the Parse service.

Table RMS-56 Parse Service FAB Output Fields
Field Name Description
FAB$L_DEV Device characteristics (unless you select the NAM$V_SYNCHK option).
FAB$L_SDC Secondary device characteristics (unless you select the NAM$V_SYNCHK option).
FAB$L_STS Completion status code (also returned in register 0).
FAB$L_STV Status value.


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

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

Table RMS-57 Parse Service NAM Input Fields
Field Name Option Description
NAM$L_ESA   Expanded string area address.
NAM$B_ESS   Expanded string area size.
NAM$L_FNB   Related file NAM block file name status bits.
NAM$B_NOP   NAM block options.
  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 expanded string.
  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_NO_SHORT_UPCASE 1 Do not uppercase the directory and file specification in the NAM$L_ESA buffer.
  NAM$V_SYNCHK Performs Parse service with no I/O.
NAM$L_RLF   Related file NAM or NAML block address.
NAM$L_RSA   Resultant string area address.
NAM$B_RSL   Resultant string length.


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

Table RMS-58 lists the NAM control block fields written as output by the Parse service.

Table RMS-58 Parse 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$W_DID 1 Directory identification (unless you select the NAM$V_SYNCHK option).
NAM$L_DIR Address of file specification directory string.
NAM$B_DIR Size of file specification directory string.
NAM$T_DVI 1 Device identification (unless you select the NAM$V_SYNCHK option).
NAM$B_ESL Expanded string length.
NAM$W_FID 1 File identification (zeroed).
NAM$W_FIRST_WILD_DIR 1 The topmost directory level to contain a wildcard.
NAM$L_FNB File name status bits: contains information about the parse results.
NAM$L_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 (zeroed).
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 context.


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

Table RMS-59 lists the NAML block fields used as input for the Parse service.

Table RMS-59 Parse Service NAML Input Fields (Alpha Only)
Field Name Option Description
NAML$L_ESA   Expanded string area address.
NAML$B_ESS   Expanded string area size.
NAML$L_FILESYS_NAME 1   File system name buffer address.
NAML$L_FILESYS_NAME_ALLOC 1   File system name buffer size.
NAML$L_FNB   Related file NAM or NAML block file name status bits.
NAML$L_INPUT_FLAGS   Additional flags specified as input.
NAML$L_LONG_DEFNAME   Long default file specification string address (used if FAB$L_DNA contains -1).
NAML$L_LONG_DEFNAME_SIZE   Long default file specification string size.
NAML$L_LONG_EXPAND   Long expanded string area address.
NAML$L_LONG_EXPAND_ALLOC 1   Long expanded string area size.
NAML$L_LONG_FILENAME   Long file specification string address (used if FAB$L_FNA contains -1).
NAML$L_LONG_FILENAME_SIZE 1   Long file specification string size.
NAML$L_LONG_RESULT   Long resultant string area address.
NAML$L_LONG_RESULT_ALLOC   Long resultant string size.
NAML$B_NOP   NAM or NAML block options.
  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 expanded string.
  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_NO_SHORT_UPCASE 1 Do not uppercase the directory and file specification in the NAML$L_ESA buffer.
  NAML$V_SYNCHK Performs Parse service with no I/O.
NAML$L_RLF   Related file NAM or NAML block address.
NAML$L_RSA   Resultant string area address.
NAML$B_RSL   Resultant string length.


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

Table RMS-60 lists the NAML block fields used as output for the Parse service.

Table RMS-60 Parse 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$W_DID 1 Directory identification (unless you select the NAML$V_SYNCHK option).
NAML$L_DIR Address of file specification directory string.
NAML$B_DIR Size of file specification directory string.
NAML$T_DVI 1 Device identification (unless you select the NAML$V_SYNCHK option).
NAML$B_ESL Expanded string length.
NAML$W_FID 1 File identification (zeroed).
NAML$L_FILESYS_NAME_SIZE 1 File system name length.
NAML$W_FIRST_WILD_DIR 1 First wild directory.
NAML$L_FNB File name status bits: contains information about the parse results.
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 Total number of directories.
NAML$L_LONG_DIR_SIZE Long directory string length.
NAML$L_LONG_EXPAND_SIZE Long expanded 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 (zeroed).
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 context.


1This field or option 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$_BUG_DDI
RMS$_CDA RMS$_CHN RMS$_DEV
RMS$_DIR RMS$_DME RMS$_DNA
RMS$_DNF RMS$_DNR RMS$_ESA
RMS$_ESS RMS$_FAB RMS$_FNA
RMS$_FNM RMS$_IFI RMS$_LNE
RMS$_NAM RMS$_NAML RMS$_NAMLESS
RMS$_NAMLFSINV RMS$_NAMLFSSIZ RMS$_NOD
RMS$_NORMAL RMS$_QUO RMS$_RLF
RMS$_RUNDOWN RMS$_STR RMS$_SUC
RMS$_SYN RMS$_TYP RMS$_VER
RMS$_WCC    


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_030.HTML