1 CQUAL_Routines The UTIL$CQUAL routines allow you to parse the command line for qualifiers related to certain file attributes, and to match files you are processing against the selected criteria retrieved from the command line. 2 UTIL$CQUAL_FILE_PARSE The UTIL$CQUAL_FILE_PARSE routine parses the command line for the common file qualifiers. Format UTIL$CQUAL_FILE_PARSE flags ,context [,found_flags] 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Longword condition value. Most utility routines return a condition value in R0. Condition Values Returned lists condition values that this routine returns. 3 Arguments flags OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Longword of bit flags. UTIL$CQUAL_FILE_PARSE scans the command line for the qualifiers whose associated bit is set in the flags longword. The following table lists the allowed mask and field specifier values. Table 3-1 UTIL$CQUAL_FILE_PARSE Flags and Masks Qualifier Mask Value Field Specifier /CONFIRM UTIL$M_CQF_ UTIL$V_CQF_CONFIRM CONFIRM /EXCLUDE UTIL$M_CQF_ UTIL$V_CQF_EXCLUDE EXCLUDE /BEFORE UTIL$M_CQF_BEFORE UTIL$V_CQF_BEFORE /SINCE UTIL$M_CQF_SINCE UTIL$V_CQF_SINCE /CREATED UTIL$M_CQF_ UTIL$V_CQF_CREATED CREATED /MODIFIED UTIL$M_CQF_ UTIL$V_CQF_MODIFIED MODIFIED /EXPIRED UTIL$M_CQF_ UTIL$V_CQF_EXPIRED EXPIRED /BACKUP UTIL$M_CQF_BACKUP UTIL$V_CQF_BACKUP /BY_ UTIL$M_CQF_ UTIL$V_CQF_BYOWNER OWNER BYOWNER context OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference The address of a longword that receives the common file qualifier database address. The address of the context variable must be passed to the UTIL$CQUAL_FILE_MATCH and UTIL$CQUAL_FILE_END routines when they are called. found_flags OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Longword of bit flags. This optional parameter is the longword address of the value that indicates which common file qualifiers were present on the command line. The mask and field specifier values are the same values as the flags parameter, and are listed in UTIL$CQUAL_FILE_PARSE Flags and Masks. 3 Description Using the CLI$PRESENT and CLI$GET_VALUE routines, the UTIL$CQUAL_ FILE_PARSE routine searches the command line for the qualifiers specified in the flags longword. When command line parsing finishes, UTIL$CQUAL_FILE_PARSE returns a pointer to the common file qualifier value in the context parameter. The context parameter must be used when calling either the UTIL$CQUAL_FILE_MATCH or UTIL$CQUAL_FILE_END routines. If a third parameter is specified, UTIL$CQUAL_FILE_PARSE returns a longword of flags indicating which qualifiers were found during the command line parse. The mask and field specifiers are listed in UTIL$CQUAL_FILE_PARSE Flags and Masks. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. LIB$_INVARG Invalid argument. A bit in the flags parameter was set without an associated qualifier. CLI$_INVQUAVAL An unusable value was given on the command line for any of the following qualifiers: /EXCLUDE, /BEFORE, /SINCE, or /BY_OWNER (for example, /BEFORE=mintchip). SS$_CONFQUAL More than one of the following appeared on the command line at the same time: /CREATED, /MODIFIED, /EXPIRED, /BACKUP. Any unsuccessful return from LIB$GET_VM. 2 UTIL$CQUAL_FILE_MATCH The UTIL$CQUAL_FILE_MATCH routine matches a file with the selection criteria. Format UTIL$CQUAL_FILE_MATCH context [,user_fab] [,file_name] [,prompt_string_1] [,prompt_string_2] [,prompt_rtn] [,current_form] [,disable] 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Longword condition value. Most utility routines return a condition value in R0. Condition Values Returned lists condition values that this routine returns. 3 Arguments context OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The longword address that received the common file qualifier database address from a prior call to UTIL$CQUAL_FILE_PARSE. user_fab OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The FAB address of the file to be evaluated. This FAB must point to a valid NAM or NAML block. If the file is open and the file header criteria are to be evaluated, the appropriate XABs (XABPRO or XABDAT) must be chained to the FAB and properly filled in by RMS. If the file is not open when this routine is called, then the XAB chain is not necessary, but may be present. This argument is optional. If it is not present, the file_name parameter must be present. Both arguments may not be present at the same time. file_name OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The file name descriptor address of the file to be processed. This parameter can be used instead of the user_fab argument. Both arguments may not be present at the same time. prompt_string_1 OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Longword address of a prompt string descriptor. This prompt is used when prompting to a terminal device and the current prompt form is UTIL$K_CQF_SHORT. prompt_string_2 OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by descriptor Longword address of a prompt string descriptor. This prompt is used when prompting to a terminal device and the current prompt form is UTIL$K_CQF_LONG. prompt_rtn OpenVMS usage:procedure type: longword (unsigned) access: function call mechanism: by value User-supplied longword routine address used for prompting and accepting input from the user. The user routine is responsible for end-of-file processing and must return RMS$_EOF when appropriate. current_form OpenVMS usage:longword_unsigned type: longword (unsigned) access: read write mechanism: by reference This optional parameter supplies the initial prompt form displayed to the user. If it contains the value UTIL$K_CQF_ UNSPECIFIED, then the form last requested by the user is used if that form is available. If there was no previous call to UTIL$CQUAL_FILE_MATCH, and the current_form is unspecified, UTIL$K_CQF_SHORT is assumed. When exiting UTIL$CQUAL_FILE_MATCH, the current_form parameter contains the last user requested prompt form. If a previous call to UTIL$CQUAL_FILE_MATCH requested quit processing or quit confirmation prompting, then this parameter is not modified. disable OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Longword of bit flags. This optional parameter specifies which common file qualifiers are ignored in the current call to UTIL$CQUAL_FILE_MATCH. Qualifiers that cannot be ignored are /CREATED, /MODIFIED, /EXPIRED, and /BACKUP). 3 Description UTIL$CQUAL_FILE_MATCH compares the file named in either the user_ fab or file_name parameter (only one can be specified) against criteria specified by the common file qualifier database pointed to by the context and the disable parameter flags. UTIL$CQUAL_ FILE_MATCH returns a status as to whether the file does or does not match the criteria. If a failure occurs during processing, such as those listed in the Abnormal Completion Codes, the routine quits processing files for the context under which the failure occurred. A processing failure is the same as receiving a quit processing response from a user prompt. Any additional calls to this routine with the context that incurred the processing failure will return UTIL$_ QIOPRO. This applies even if the user responded ALL to a previous confirmation prompt. For a description of the /CONFIRM prompting, see UTIL$CQUAL_ CONFIRM_ACT. NOTE The UTIL$CQUAL_FILE_MATCH current_form parameter is different from the same parameter in UTIL$CQUAL_CONFIRM_ ACT. UTIL$CQUAL_FILE_MATCH retains the user's last requested form between calls. 3 Condition_Values_Returned Normal Completion Codes: SS$_NORMAL File matches the criteria and can be processed. UTIL$_QUICONACT User requests that confirmation prompting cease, but that other common file qualifier criteria be applied on subsequent file specifications. UTIL$_FILFAIMAT File failed the evaluation, and should not be processed. UTIL$QUIPRO User requests that processing stops. Abnormal Completion Codes: LIB$INVARG Incorrect parameter list. SS$_ACCVIO Unable to access one or more of the parameters (such as the common file database or user_ fab). UTIL$_FILFID File specification contains an FID. Due to file specification aliases, converting an FID to a file specification is inappropriate for /EXCLUDE processing. UTIL$_FILDID File specification contains a DID. Due to directory specification aliases, converting a DID to a directory patch is inappropriate for /EXCLUDE processing when the directory patch needs to be compared. LIB$_INVXAB Invalid XAB chain. A necessary XAB (XABPRO or XABDAT) is missing from the opened file's XAB chain. Any unsuccessful code from RMS, LIB$GET_VM, or any unsuccessful return status from the user-supplied routine (other than RMS$_ EOF). 2 UTIL$CQUAL_FILE_END The UTIL$CQUAL_FILE_END routine returns all allocated virtual memory from the call to UTIL$CQUAL_FILE_PARSE. Format UTIL$CQUAL_FILE_END context 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Longword condition value. Most utility routines return a condition value in R0. Condition Values Returned lists condition values that this routine returns. 3 Arguments context OpenVMS usage:longword_unsigned type: longword (unsigned) access: read write mechanism: by reference The longword address that received the common file qualifier database address from a prior call to UTIL$CQUAL_FILE_PARSE. 3 Description UTIL$CQUAL_FILE_END deallocates the virtual memory obtained by the common file qualifier package during the call to UTIL$CQUAL_ FILE_PARSE. The virtual memory held information for calls to UTIL$CQUAL_FILE_MATCH. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. Any unsuccessful code from LIB$FREE_VM. 2 UTIL$CQUAL_CONFIRM_ACT The UTIL$CQUAL_CONFIRM_ACT routine prompts the user for confirmation, using the optional prompt routine if present, and returns an indication of the user's response. Format UTIL$CQUAL_CONFIRM_ACT [prompt_string_1] [,prompt_string_2] [,prompt_rtn] [,current_form] 3 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Longword condition value. Most utility routines return a condition value in R0. Condition Values Returned lists condition values that this routine returns. 3 Arguments prompt_string_1 OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by descriptor Longword address of a prompt string descriptor. The prompt is used when prompting to a terminal device, and the current prompt form is UTIL$K_CQF_SHORT. prompt_string_2 OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by descriptor Longword address of a prompt string descriptor. The prompt is used when prompting to a terminal device, and the current prompt form is UTIL$K_CQF_LONG. prompt_rtn OpenVMS usage:procedure type: longword (unsigned) access: function call mechanism: by value Longword address of a user-supplied routine for prompting and accepting user input. The user routine is responsible for end-of- file processing and must return RMS$_EOF when appropriate. current_form OpenVMS usage:longword_unsigned type: longword (unsigned) access: read write mechanism: by reference This optional parameter supplies the initial prompt form to be displayed to the user. If present, this parameter receives the form of the last prompt displayed. The following table shows the valid prompting form values: Table 3-2 Prompting Form Values Value Description UTIL$K_CQF_SHORT Use prompt_string_1. UTIL$K_CQF_LONG Use prompt_string_2. UTIL$K_CQF_UNSPECIFIED None specified; use default. 3 Description UTIL$CQUAL_CONFIRM_ACT prompts the user for confirmation. You must supply at least one prompt string to this routine. If you supply both strings, you should have an expanded and condensed form of the prompt. The condensed form should be supplied through the prompt_string_1 parameter; the expanded form through prompt_ string_2. The prompt string supplied by prompt_string_1 is initially used if the prompt_string_1 is present, does not have a length of zero, and either: o The current_form parameter is not specified o The current_form parameter is specified and contains: - UTIL$K_CQF_SHORT - UTIL$K_CQF_UNSPECIFIED - A value greater than UTIL$K_CQF_MAX_FORM The prompt string supplied by prompt_string_2 is used initially if prompt_string_2 is present, does not have a length of zero, and either: o prompt_string_1 is not present or has a length of zero o The current_form parameter is specified and contains the value UTIL$K_CQF_LONG Once the initial form is displayed, the user can switch between the two forms by responding to the prompt with either CONDENSED or EXPANDED. The user can only switch to another form if there was a prompt string provided for that form. Responding with either CONDENSED or EXPANDED causes a reprompt to occur, even if the current display form was not switched. If a prompt routine is provided, the routine is called with the address of the prompt string descriptor in the first parameter, and the string descriptor address to receive the user's response in the second parameter. The routine returns a success status or RMS$_EOF. If an unsuccessful status other than RMS$_EOF is received, then UTIL$CQUAL_CONFIRM_ACT exits without processing any response in the response buffer (the second parameter that was passed to the prompt routine). UTIL$CQUAL_CONFIRM_ACT returns the status received from the user prompt routine. The prompt routine is responsible for end-of-file processing, and must return RMS$_EOF when appropriate. If an optional prompt routine is provided, it should be provided for all calls to UTIL$CQUAL_CONFIRM_ACT. Not doing so can cause unpredictable end-of-file processing. When the user is prompted, they may respond with the following: Table 3-3 Prompt Responses Positive Negative Stop Stop Switch Response Response Processing Prompting Prompts YES NO QUIT ALL CONDENSED TRUE FALSE Ctrl/Z EXPANDED 1 0 NOTE Entering ALL assumes that subsequent files are a positive response from the user, and no further prompting occurs. The routine UTIL$CQUAL_FILE_MATCH properly handles this response. Since UTIL$CQUAL_CONFIRM_ACT does not contain context from a previous call, callers of this routine should not call UTIL$CQUAL_CONFIRM_ACT if the user has previously responded ALL unless the application needs explicit confirmation on certain items. The user can use any combination of uppercase and lowercase letters for word responses. Word responses can be abbreviated to one or more letters (for example, T, TR, or TRU for TRUE), but these abbreviations must be unique. After a valid response is received from the user, the procedure returns the current_form parameter. The current_form parameter contains the last form presented to the user if it was specified and write access is permitted. 3 Condition_Values_Returned SS$_NORMAL Positive answer. LIB$_NEGANS Negative answer. UTIL$_QUIPRO Quit processing. UTIL$_QUICONACT Continue processing, but cease prompting. LIB$_INVARG Invalid argument list (no prompt strings). SS$_ACCVIO Access violation (on user routine address). Any unsuccessful return from RMS, SYS$ASSIGN, $QIOW, or from the user-supplied routine (other than RMS$_EOF).