HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

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.

Table RMS-56 lists the FAB control block fields written as output by the Parse service.

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-58 lists the NAM control block fields written as output by the Parse service.

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

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

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.