Format

ACLEDIT$EDIT item_list

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Argument

item_list

Item list used by the callable ACL editor. The item_list argument is the address of one or more descriptors of arrays, routines, or longword bit masks that control various aspects of the editing session.

Each entry in an item list is in the standard format shown in the following figure:

Description

Use the ACLEDIT$EDIT routine to create and modify an ACL associated with any security object.

Under normal circumstances, the application calls the ACL editor to modify an object's ACL, and control is returned to the application when you finish or abort the editing session.

If you also want to use a customized version of the ACL editor section file, the logical name ACLEDT$SECTION should be defined. See the VSI OpenVMS System Management Utilities Reference Manual for more information.

Condition Values Returned

Format

Returns

Longword condition value. Condition values that this routine can return are listed under Condition Values Returned.

Argument

argument-buffer

Arguments that specify the BACKUP operation to be performed. The argument-buffer argument is the address of a variable-length array of one or more Backup API option structures that define the attributes of the requested BACKUP operation. The variable-length array is terminated by an option structure of 16 bytes that contains all zeros. Table 3.2, “BACKUP Option Structure Types” describes the option structures.

Description

Application programs call the Backup API to invoke the OpenVMS Backup utility via a call to the BACKUP$START routine. There is only one parameter, the address of an argument buffer that contains a number of option structures that together define the operation requested of the Backup utility. Most of these option structures are equivalent, singly or in combination, to the qualifiers available when invoking the BACKUP utility with the DCL command BACKUP; the call to the API is analogous to a user entering an interactive command to the Backup utility.

The call to BACKUP$START is synchronous; that is, it does not return until the operation is complete or is terminated by a fatal error. In the case of a fatal error, the call is aborted.

BACKUP Event Callbacks

An application can request that the BACKUP API notify the application whenever specific events occur. The application can specify different callback routines to handle different types of BACKUP events, or one routine to handle all events. To do so, the application registers the callback routine by including option structure BCK_OPTYP_K_EVENT_CALLBACK in the call to BACKUP$START. This option structure specifies an event type (or all events) and the address of a routine to be called when the event occurs. The application must include one such option structure for each requested event type. To specify all events, use BCK_EVENT_K_ALL. Table 3.4, “Event Callback Buffer Formats” lists the specific event types and identifiers.

A callback routine:

The bckEvent structure contains information about the type of event, and also contains a descriptor of a data structure that contains information to be used to process the event. The bckEvent structure may point to a bckControl structure that specifies control aspects of an event that may require user or operator action.

Table 3.3, “bckEvent Format” describes the format of the bckEvent data structure. Table 3.6, “bckControl Format” describes the format of the bckControl data structure.

Table 3.4, “Event Callback Buffer Formats” describes the values returned in the bckEvent data structure.

Table 3.5, “Control Event Subtypes” describes the control event subtypes of the BCK_EVENT_K_CONTROL event callback. Table 3.6, “bckControl Format” describes the format of the bckControl data structure.

Control events are described by the Control event subtype, via the bckevt_l_event_subtype field in the bckEvent structure. Table 3.6, “bckControl Format” describes the format of the bckControl data structure.

Error Messages

Where possible, the Backup API emulates the behavior of the interactive BACKUP utility if you pass a call that contains conflicting qualifiers by:

See the VSI OpenVMS System Management Utilities Reference Manual for a table of valid combinations of BACKUP qualifiers.

Condition Values Returned

Any condition value returned by the OpenVMS Backup utility.

Example

The following C example program demonstrates calling the Backup API to perform the following DCL commands:

$ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1_IN:*.*;* -
_$ APITEST1_OUT:A.BCK/SAVE_SET

$ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1_OUT:A.BCK/SAVE_SET -
_$ APITEST2_OUT:*.*;*

#include <stdio.h>
#include <stdlib.h>
#include <ssdef.h>
#include <descrip.h>
#include "sys$examples:bapidef.h"

/*
** Define a fixed size (simple) structure for specifying the
** BACKUP operation.
*/
typedef struct _buf_arg
               {
                bck_opt_struct_flag arg1;
                bck_opt_struct_flag arg2;
                bck_opt_struct_flag arg3;
                bck_opt_struct_flag arg4;
                bck_opt_struct_dsc arg5;
                bck_opt_struct_dsc arg6;
                bck_opt_struct_flag arg7;
                bck_opt_struct_flag arg8;
                bck_opt_struct_adr arg9;
                bck_opt_struct_adr arg10;
                bck_opt_struct_adr arg11;
                bck_opt_struct_flag arg12;
                bck_opt_struct_flag arg13;
               } buf_arg;


struct dsc$descriptor
               input_dsc,
               output_dsc,
               event_type_dsc;
buf_arg myarg_buff;
unsigned int status;

extern unsigned int backup$start(buf_arg  *myarg_buff);
unsigned int subtest(bckEvent *param);

static char  input_str[]      = "APITEST1_IN:";
static char  output_str1[]      = "APITEST1_OUT:a.bck";
static char  output_str2[]      = "APITEST2_OUT:";

main()
{
 myarg_buff.arg1.option_type = BCK_OPT_K_ALIAS;
 myarg_buff.arg1.opt_flag_value = TRUE;

 myarg_buff.arg2.option_type = BCK_OPT_K_VERIFY;
 myarg_buff.arg2.opt_flag_value = TRUE;

 myarg_buff.arg3.option_type = BCK_OPT_K_CRC;
 myarg_buff.arg3.opt_flag_value = TRUE;

 myarg_buff.arg4.option_type = BCK_OPT_K_LOG;
 myarg_buff.arg4.opt_flag_value = TRUE;

 myarg_buff.arg5.opt_dsc_type = BCK_OPT_K_INPUT;
 myarg_buff.arg5.opt_dsc.dsc$b_dtype = DSC$K_DTYPE_T;
 myarg_buff.arg5.opt_dsc.dsc$b_class = DSC$K_CLASS_S;
 myarg_buff.arg5.opt_dsc.dsc$w_length = sizeof(input_str) - 1;
 myarg_buff.arg5.opt_dsc.dsc$a_pointer = input_str;


 myarg_buff.arg6.opt_dsc_type = BCK_OPT_K_OUTPUT;
 myarg_buff.arg6.opt_dsc.dsc$b_dtype = DSC$K_DTYPE_T;
 myarg_buff.arg6.opt_dsc.dsc$b_class = DSC$K_CLASS_S;
 myarg_buff.arg6.opt_dsc.dsc$w_length = sizeof(output_str1) - 1;
 myarg_buff.arg6.opt_dsc.dsc$a_pointer = output_str1;

 myarg_buff.arg7.option_type = BCK_OPT_K_SAVE_SET_OUT;
 myarg_buff.arg7.opt_flag_value = TRUE;

 myarg_buff.arg8.option_type = BCK_OPT_K_OPERATION_TYPE;
 myarg_buff.arg8.opt_flag_value = BCK_OP_K_SAVE ;

 myarg_buff.arg9.opt_adr_type = BCK_OPT_K_EVENT_CALLBACK;
 myarg_buff.arg9.opt_adr_attributes = BCK_EVENT_K_LOG;
 myarg_buff.arg9.opt_adr_value[0] = (int *)subtest;
 myarg_buff.arg9.opt_adr_value[1] = 0;


 /*
 ** Specify that this application will handle user-visible messages.
 ** (The operation phase, and user/file-logging messages.)
 */
 myarg_buff.arg10.opt_adr_type = BCK_OPT_K_EVENT_CALLBACK;
 myarg_buff.arg10.opt_adr_attributes = BCK_EVENT_K_OP_PHASE;
 myarg_buff.arg10.opt_adr_value[0] = (int *)subtest;
 myarg_buff.arg10.opt_adr_value[1] = 0;

 myarg_buff.arg11.opt_adr_type = BCK_OPT_K_EVENT_CALLBACK;
 myarg_buff.arg11.opt_adr_attributes = BCK_EVENT_K_USER_MSG;
 myarg_buff.arg11.opt_adr_value[0] = (int *)subtest;
 myarg_buff.arg11.opt_adr_value[1] = 0;


 /*
 ** Indicate the end of options that specify the BACKUP operation
 ** to be performed.
 */
 myarg_buff.arg12.option_type = BCK_OPT_K_END_OPT;
 myarg_buff.arg12.opt_flag_value = FALSE;

 /*
 ** Notes:
 **  An extra option structure (# 13) was allocated for testing.
 **
 **  The DCL command analogous to the following BACKUP API call
 ** is illustrated below.
 **
 ** "$ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1_IN:*.*;* -"
 ** "_$  APITEST1_OUT:a.bck/SAVE_SET "
 */


        status = backup$start(&myarg_buff);

 if (! (status & 1))
 {
     exit (status);  /* EXIT if the first part of the test failed. */
 }

 /*
 **  Now use the resultant saveset to perform a restore operation.
 */

 /*
 **  Change the input string to specify the saveset, ("output_str1").
 */
 myarg_buff.arg5.opt_dsc.dsc$w_length = sizeof(output_str1) - 1;
 myarg_buff.arg5.opt_dsc.dsc$a_pointer = output_str1;


 /*
 **  Change the output string to specify the output device/directory).
 */
 myarg_buff.arg6.opt_dsc.dsc$w_length = sizeof(output_str2) - 1;
 myarg_buff.arg6.opt_dsc.dsc$a_pointer = output_str2;

 /*
 **  Change the option to denote it is now an input saveset,
 **  (not an output saveset).
 */
 myarg_buff.arg7.option_type = BCK_OPT_K_SAVE_SET_IN;


 /*
 **  Change the option to specify a restore operation,
 **  (not a save operation).
 */
 myarg_buff.arg8.opt_flag_value = BCK_OP_K_RESTORE;

 /*
 **  The DCL command analogous to the following BACKUP API call
 ** is illustrated below.
 **
 ** "$ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1_OUT:a.bck/SAVE_SET -"
 ** "_$  APITEST2_OUT:*.*;*"
 */

 status = backup$start(&myarg_buff);

        exit (status);
}


unsigned int subtest(bckEvent *param)
{

 printf("\n BACKUP API Event Type = %d,\n",param->bckevt_l_event_type);
 printf("               Subtype = %d\n",param->bckevt_l_event_subtype);

 if (param->bckevt_l_event_type == BCK_EVENT_K_LOG)
 {
     printf(" BACKUP API LOG Event item:\n %.*s\n",
      param->bckevt_r_event_buffer.dsc$w_length,
      param->bckevt_r_event_buffer.dsc$a_pointer);
 }


 if (param->bckevt_l_event_type == BCK_EVENT_K_OP_PHASE)
 {
     printf(" BACKUP API Operation Phase Event\n %.*s\n",
      param->bckevt_r_event_buffer.dsc$w_length,
      param->bckevt_r_event_buffer.dsc$a_pointer);
 }

 fflush(stdout);

        return (1);
} 

Format

CLI$DCL_PARSE [command_string] ,table [,param_routine]  [,prompt_routine] [,prompt_string]

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

Character string containing the command to be parsed. The command_string argument is the address of a descriptor specifying the command string to be parsed. If the command string includes a comment (delimited by an exclamation mark), DCL ignores the comment.

If the command string contains a hyphen to indicate that the string is being continued, DCL uses the routine specified in the prompt_routine argument to obtain the rest of the string. The command string is limited to 256 characters. However, if the string is continued with a hyphen, CLI$DCL_PARSE can prompt for additional input until the total number of characters is 1024.

If you specify the command_string argument as zero and specify a prompt routine, then DCL prompts for the entire command string. However, if you specify the command_string argument as zero and also specify the prompt_routine argument as zero, DCL restores the parse state of the command string that originally invoked the image.

CLI$DCL_PARSE does not perform DCL-style symbol substitution on the command string.

Address of the compiled command tables to be used for command parsing. The command tables are compiled separately by the Command Definition Utility using the DCL command SET COMMAND/OBJECT and are then linked with your program. A global symbol is defined by the Command Definition Utility that provides the address of the tables. The global symbol's name is taken from the module name given on the MODULE statement in the command definition file, or from the file name if no MODULE statement is present.

Name of a routine to obtain a required parameter not supplied in the command text. The param_routine argument is the address of a routine containing a required parameter that was not specified in the command_string argument.

To specify the parameter routine, use the address of LIB$GET_INPUT or the address of a routine of your own that has the same three-argument calling format as LIB$GET_INPUT. See the description of LIB$GET_INPUT in the VSI OpenVMS RTL Library (LIB$) Manual for information about the calling format.

If LIB$GET_INPUT returns error status, CLI$DCL_PARSE propagates the error status outward or signals RMS$_EOF in the cases listed in the Description section.

You can obtain the prompt string for a required parameter from the command table specified in the table argument.

Name of a routine to obtain all or part of the text of a command. The prompt_routine argument is the address of a routine to obtain the text or the remaining text of the command depending on the command_string argument. If you specify a zero in the command_string argument, DCL uses this routine to obtain an entire command line. DCL uses this routine to obtain a continued command line if the command string (obtained from the command_string argument) contains a hyphen to indicate that the string is being continued.

To specify the prompt routine, use the address of LIB$GET_INPUT or the address of a routine of your own that has the same three-argument calling format as LIB$GET_INPUT. See the description of LIB$GET_INPUT in the VSI OpenVMS RTL Library (LIB$) Manual for information about the calling format.

If LIB$GET_INPUT returns error status, CLI$DCL_PARSE propagates the error status outward or signals RMS$_EOF in the cases listed in the Description section.

Character string containing a prompt. The prompt_string argument is the address of a string descriptor pointing to the prompt string to be passed as the second argument to the prompt_routine argument.

If DCL is using the prompt routine to obtain a continuation line, DCL inserts an underscore character before the first character of the prompt string to create the continuation prompt. If DCL is using the prompt routine to obtain an entire command line (that is, a zero was specified as the command_string argument), DCL uses the prompt string exactly as specified.

The prompt string is limited to 32 characters. The string COMMAND> is the default prompt string.

Description

The CLI$DCL_PARSE routine supplies a command string to DCL for parsing. DCL parses the command string according to the syntax in the command table specified in the table argument.

The CLI$DCL_PARSE routine can prompt for required parameters if you specify a parameter routine in the routine call. In addition, the CLI$DCL_PARSE routine can prompt for entire or continued command lines if you supply the address of a prompt routine.

If you do not specify a command string to parse and the user enters a null string in response to the DCL prompt for a command string, CLI$DCL_PARSE immediately terminates and returns the status CLI$_NOCOMD.

If DCL prompts for a required parameter and the user presses Ctrl/Z, CLI$DCL_PARSE immediately terminates and returns the status CLI$_NOCOMD, regardless of whether you specify or do not specify a command string to parse. If DCL prompts for a parameter that is not required and the user presses Ctrl/Z, CLI$DCL_PARSE returns the status CLI$_NORMAL.

Whenever CLI$DCL_PARSE encounters an error, it both signals and returns the error.

Condition Values Returned

Format

CLI$DISPATCH [userarg]

Returns

Longword condition value. Most utility routines return a condition value in R0. The condition value that this routine can return is listed under Condition Values Returned.

Argument

Data to be passed to the action routine. The userarg argument is a longword that contains the data to be passed to the action routine. This data can be used in any way you want.

Description

The CLI$DISPATCH routine invokes the subroutine associated with the verb most recently parsed by a CLI$DCL_PARSE routine call. If the routine is successfully invoked, the return status is the status returned by the action routine. Otherwise, a status of CLI$_INVROUT is returned.

Condition Values Returned

Format

CLI$GET_VALUE entity_desc ,retdesc [,retlength]

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

The entity_desc argument can contain qualifiers, parameters, keyword names, or labels that were assigned with the LABEL clause in the command definition file. If you used the LABEL clause to assign a label to an entity, you must specify the label in the entity_desc argument. Otherwise, use the name of the entity.

Use a keyword path to reference keywords used as values of parameters, qualifiers, or other keywords. A keyword path contains a list of entity names or labels separated by periods. If the LABEL clause was used to assign a label to an entity, you must specify the label in the keyword path. Otherwise, you must use the name of the entity.

$ NEWCOMMAND/QUAL1=(START=5,END=10)/QUAL2=(START=2,END=5)

The keyword path QUAL1.START identifies the START keyword when it is used with QUAL1; the keyword path QUAL2.START identifies the keyword START when it is used with QUAL2. Because the name START is an ambiguous reference if used alone, the keywords QUAL1 and QUAL2 are needed to resolve the ambiguity.

You can omit keywords from the beginning of a keyword path if they are not needed to unambiguously resolve a keyword reference. A keyword path can be no more than eight names long.

DCL uses the first occurrence of the entity as the keyword path. Note that DCL does not issue an error message if you provide an ambiguous keyword. However, because the keyword search order may change in future releases of OpenVMS, you should never use ambiguous keyword references.

If the entity_desc argument does not exist in the command table, CLI$GET_VALUE signals a syntax error (by means of the signaling mechanism described in the VSI OpenVMS Programming Concepts Manual).

Character string containing the value retrieved by CLI$GET_VALUE. The retdesc argument is the address of a string descriptor pointing to the buffer to receive the string value retrieved by CLI$GET_VALUE. The string is returned using the STR$COPY_DX Run-Time Library routine.

If there are errors in the specification of the return descriptor or in copying the results using that descriptor, the STR$COPY_DX routine will signal the errors. For a list of these errors, see the VSI OpenVMS RTL String Manipulation (STR$) Manual.

Word containing the number of characters DCL returns to retdesc. The retlength argument is the address of the word containing the length of the retrieved value.

Description

To obtain the values for a list of entities, call CLI$GET_VALUE repeatedly until all values have been returned. After each CLI$GET_VALUE call, the returned condition value indicates whether there are more values to be obtained. Call CLI$GET_VALUE until you receive a condition value of CLI$_ABSENT.

When you are using CLI$GET_VALUE to obtain a list of qualifier or keyword values, get all values in the list before starting to parse the next entity.

Condition Values Returned

Format

CLI$PRESENT entity_desc

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Argument

A keyword path is used to reference keywords that are accepted by parameters, qualifiers, or other keywords. A keyword path contains a list of entity names separated by periods. See the description of the entity_desc argument in the CLI$GET_VALUE routine for more information about specifying keyword paths as arguments for CLI routines.

The entity_desc argument can contain parameter, qualifier, or keyword names, or can contain labels that were assigned with the LABEL clause in the command definition file. If the LABEL clause was used to assign a label to a qualifier, parameter, or keyword, you must specify the label in the entity_desc argument. Otherwise, you must use the actual name of the qualifier, parameter, or keyword.

If the entity_desc argument does not exist in the command table, CLI$PRESENT signals a syntax error (by means of the signaling mechanism described in the VSI OpenVMS Programming Concepts Manual).

Description

The CLI$PRESENT routine examines the parsed command string to determine whether the entity referred to by the entity_desc argument is present.

When CLI$PRESENT tests whether a qualifier is present, the condition value indicates whether the qualifier is used globally or locally. You can use a global qualifier anywhere in the command line; you use a local qualifier only after a parameter. A global qualifier is defined in the command definition file with PLACEMENT=GLOBAL; a local qualifier is defined with PLACEMENT=LOCAL.

When you test for the presence of a global qualifier, CLI$PRESENT determines if the qualifier is present anywhere in the command string. If the qualifier is present in its positive form, CLI$PRESENT returns CLI$_PRESENT; if the qualifier is present in its negative form, CLI$PRESENT returns CLI$_NEGATED.

You can test for the presence of a local qualifier when you are parsing parameters that can be followed by qualifiers. After you call CLI$GET_VALUE to fetch the parameter value, call CLI$PRESENT to determine whether the local qualifier is present. If the local qualifier is present in its positive form, CLI$PRESENT returns CLI$_LOCPRES; if the local qualifier is present in its negative form, CLI$PRESENT returns CLI$_LOCNEG.

A positional qualifier affects the entire command line if it appears after the verb but before the first parameter. A positional qualifier affects a single parameter if it appears after a parameter. A positional qualifier is defined in the command definition file with the PLACEMENT=POSITIONAL clause.

To determine whether a positional qualifier is used globally, call CLI$PRESENT to test for the qualifier before you call CLI$GET_VALUE to fetch any parameter values. If the positional qualifier is used globally, CLI$PRESENT returns either CLI$_PRESENT or CLI$_NEGATED.

To determine whether a positional qualifier is used locally, call CLI$PRESENT immediately after a parameter value has been fetched by CLI$GET_VALUE. The most recent CLI$GET_VALUE call to fetch a parameter defines the context for a qualifier search. Therefore, CLI$PRESENT tests whether a positional qualifier was specified after the parameter that was fetched by the most recent CLI$GET_VALUE call. If the positional qualifier is used locally, CLI$PRESENT returns either CLI$_LOCPRES or CLI$_LOCNEG.

Condition Values Returned

Format

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition Values Returned lists condition values that this routine returns.

Argument

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.

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.

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 Table 5.3, “UTIL$CQUAL_FILE_PARSE Flags and Masks”.

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 Table 5.3, “UTIL$CQUAL_FILE_PARSE Flags and Masks”.

Condition Values Returned

Any unsuccessful return from LIB$GET_VM.

Format

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition Values Returned lists condition values that this routine returns.

Argument

context

The longword address that received the common file qualifier database address from a prior call to UTIL$CQUAL_FILE_PARSE.

user_fab

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

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

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

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

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

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

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

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.

Condition Values Returned

Normal Completion Codes:

Abnormal Completion Codes:

Any unsuccessful code from RMS, LIB$GET_VM, or any unsuccessful return status from the user-supplied routine (other than RMS$_EOF).

Format

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition Values Returned lists condition values that this routine returns.

Argument

context

The longword address that received the common file qualifier database address from a prior call to UTIL$CQUAL_FILE_PARSE.

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.

Condition Values Returned

Any unsuccessful code from LIB$FREE_VM.

Format

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition Values Returned lists condition values that this routine returns.

Argument

prompt_string_1

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

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

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

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:

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:

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:

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:

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.

Condition Values Returned

Any unsuccessful return from RMS, SYS$ASSIGN, $QIOW, or from the user-supplied routine (other than RMS$_EOF).

Format

CONV$CONVERT [status_block_address] [,flags] [,callback_routine]

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

The conversion statistics. The status_block_address argument is the address of a variable-length array of longwords that receives statistics about the conversion.

You can request conversion statistics using zero-based, symbolic offsets (CONV$K_) into the variable-length array of longwords that contains the statistics. The array is defined as a structure (CONV$STATISTICS) of named longwords (CONV$L_) to support access by high-level programming languages.

By default, an error status is returned rather than signaled.

Name of a user-supplied routine to process the statistics information. The callback_routine argument is the address of the procedure value of a user-supplied routine to call at the completion of each key load.

Condition Values Returned

Format

CONV$PASS_FILES input_filespec ,output_filespec [,fdl_filespec] [,exception_filespec] [,flags]

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

The name of the file to be converted. The input_filespec argument is the address of a string descriptor pointing to the name of the file to be converted.

The name of the file that receives the records from the input file. The output_filespec argument is the address of a string descriptor pointing to the name of the file that receives the records from the input file.

The name of the FDL file that defines the output file. The fdl_filespec argument is the address of a string descriptor pointing to the name of the FDL file.

The name of the file that receives copies of records that cannot be written to the output file. The exception_filespec argument is the address of a string descriptor pointing to this name.

Flags (or masks) that control how the fdl_filespec argument is interpreted and how errors are signaled. The flags argument is the address of a longword containing the control flags (or mask). If you omit this argument or specify it as zero, no flags are set. If you specify a flag, it remains in effect until you explicitly reset it in a subsequent call to a CONVERT routine.

By default, an error status is returned rather than signaled.

Description

status = CONV$PASS_FILES (input_filespec)

The additional calls must immediately follow the original call that specified the output file specification.

Wildcard characters are not allowed in the file specifications passed to the CONVERT routines.

Condition Values Returned

Format

CONV$PASS_OPTIONS [parameter_list_address] [,flags]

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

To assign individual values to the CONVERT qualifiers, access the array and specify the desired value ( 1 or 0). See the VSI OpenVMS Record Management Utilities Reference Manual for detailed descriptions of the CONVERT qualifiers.

If you specify /EXIT and the utility encounters an exception record, CONVERT returns with a fatal exception status.

If you specify an FDL file specification in the CONV$PASS_FILES routine, you must place a 1 in the FDL longword. If you also specify an exceptions file specification in the CONV$PASS_FILES routine, you must place a 1 in the EXCEPTION longword. You may specify either, both, or neither of these files, but the values in the CONV$PASS_FILES call must match the values in the parameter list. If they do not, the routine returns an error.

If the size of the options block that you pass to CONV$PASS_OPTIONS includes the SECONDARY longword value, then you must specify a value for the IGNORE_PROLOGUE field.

This field is used in conjunction with the PROLOGUE offset to determine if the prologue version of the output file is to be taken from a passed FDL, the input file, the process default or system default, or from the options block itself.

A value of 0 (zero) for the IGNORE_PROLOGUE field indicates that the prologue version of the output file is to be taken from the PROLOGUE value specified in the options block.

If the PROLOGUE value in the options block contains a 0 (zero), the process default or system default prologue version will be used. This will override the prologue version specified in an FDL file or in the input file's characteristics.

A value of 1 (one) for the IGNORE_PROLOGUE field implies that the prologue version of the output file will come from the FDL file (if specified) or from the input file's characteristics.

Flags (or masks) that control how the fdl_filespec argument, used in calls to the CONV$PASS_FILES routine, is interpreted and how errors are signaled. The flags argument is the address of a longword containing the control flags (or a mask). If you omit this argument or specify it as zero, no flags are set. If you specify a flag, it remains in effect until you explicitly reset it in a subsequent call to a CONVERT routine.

By default, an error status is returned rather than signaled.

Description

$ CONVERT/FAST_LOAD/SORT/WORK_FILES=6/EXIT

OPTIONS ARRAY [12]         {Allocate a 13-cell array}
OPTIONS[0]  =  12          {Number of options]
OPTIONS[1]  =   1          {Specifies the /CREATE option}
OPTIONS[2]  =   0          {Specifies the /NOSHARE option}
OPTIONS[3]  =   1          {Specifies the /FAST_LOAD option}
OPTIONS[4]  =   0          {Specifies the /NOMERGE option}
OPTIONS[5]  =   0          {Specifies the /NOAPPEND option}
OPTIONS[6]  =   1          {Specifies the /SORT option}
OPTIONS[7]  =   6          {Specifies the /WORK_FILES=6 option}
OPTIONS[8]  =   0          {Specifies the /KEY=0 option}
OPTIONS[9]  =   0          {Specifies the /NOPAD option}
OPTIONS[10] =   0          {Specifies the null pad character}
OPTIONS[11] =   0          {Specifies the /NOTRUNCATE option}
OPTIONS[12] =   1          {Specifies the /EXIT option}

Condition Values Returned

Format

CONV$RECLAIM input_filespec [,statistics_blk] [,flags] [key_number]

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

Name of the Prolog 3 indexed file to be reclaimed. The input_filespec argument is the address of a string descriptor pointing to the name of the Prolog 3 indexed file.

Bucket reclamation statistics. The statistics_blk argument is the address of a variable-length array of longwords that receives statistics on the bucket reclamation. You can choose which statistics you want returned by specifying a number in the first element of the array. This number determines how many of the four possible statistics the routine returns.

You can request bucket reclamation statistics using symbolic names or numeric offsets into the variable-length array of longwords that contains the statistics. The array is defined as a structure of named longwords (RECL$STATISTICS) to support access by high-level programming languages.

By default, an error status is returned rather than signaled.

The optional key_number argument permits the calling program to selectively reclaim buckets by key number. If the calling program omits this argument or passes a NULL value in the argument, all buckets are reclaimed, without regard to key designation. If the calling program passes a valid key number as the value for this argument, the routine reclaims only the buckets for the specified key.

Condition Values Returned

Format

DCX$ANALYZE_DATA context ,record

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

Value identifying the data stream that DCX$ANALYZE_DATA analyzes. The context argument is the address of a longword containing this value. DCX$ANALYZE_INIT initializes this value; you should not modify it. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.

Record to be analyzed. DCX$ANALYZE_DATA reads the record argument, which is the address of a descriptor for the record string. The maximum length of the record string is 65,535 characters.

Description

The DCX$ANALYZE_DATA routine performs statistical analysis on a single data record. This routine is called once for each data record to be analyzed.

During analysis, the DCX facility gathers information that DCX$MAKE_MAP uses to create the compression/expansion function for the file. After the data records have been analyzed, call the DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status code from DCX$MAKE_MAP, you must again analyze the same data records (in the same order) using DCX$ANALYZE_DATA and then call DCX$MAKE_MAP again. On the second iteration, DCX$MAKE_MAP returns the DCX$_NORMAL status code, and the data analysis is complete.

Condition Values Returned

This routine also returns any condition values returned by LIB$ANALYZE_SDESC_R2.

Format

DCX$ANALYZE_DONE context

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Argument

Value identifying the data stream that DCX$ANALYZE_DONE deletes. The context argument is the address of a longword containing this value. DCX$ANALYZE_INIT initializes this value; you should not modify it. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.

Condition Values Returned

This routine also returns any condition values returned by LIB$FREE_VM.

Format

DCX$ANALYZE_INIT context [,item_code ,item_value]

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

Value identifying the data stream that DCX$ANALYZE_INIT initializes. The context argument is the address of a longword containing this value. DCX$ANALYZE_INIT writes this context into the context argument; you should not modify its value. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.

Item code specifying information that you want DCX$ANALYZE_INIT to use in its analysis of data records and in its computation of the mapping function. DCX$ANALYZE_INIT reads this item_code argument, which is the address of the longword contained in the item code.

For each item_code argument specified in the call, you must also specify a corresponding item_value argument. The item_value argument contains the interpretation of the item_code argument.

Value of the corresponding item_code argument. DCX$ANALYZE_INIT reads the item_value argument, which is the address of a longword containing the item value.

The item_code and item_value arguments always occur as a pair, and together they specify one piece of “advice” for the DCX routines to use in computing the map function. Note that, unless stated otherwise in the list of item codes and item values, no piece of “advice” is binding on DCX; that is, DCX is free to follow or not to follow the “advice.”

Description

The DCX$ANALYZE_INIT routine initializes the context area for a statistical analysis of the data records to be compressed. The first (and typically the only) argument passed to DCX$ANALYZE_INIT is an integer variable to contain the context value. The DCX facility assigns a value to the context variable and associates the value with the created work area. Each time you want a record analyzed in that area, specify the associated context variable. You can analyze two or more files at once by creating a different work area for each file, giving each area a different context variable, and analyzing the records of each file in the appropriate work area.

Condition Values Returned

This routine also returns any condition values returned by LIB$GET_VM.

Format

DCX$COMPRESS_DATA context ,in_rec ,out_rec [,out_length]

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

Value identifying the data stream that DCX$COMPRESS_DATA compresses. The context argument is the address of a longword containing this value. DCX$COMPRESS_INIT initializes the value; you should not modify it. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.

Data record to be compressed. The in_rec argument is the address of the descriptor of the data record string.

Data record that has been compressed. The out_rec argument is the address of the descriptor of the compressed record that DCX$COMPRESS_DATA returns.

Length (in bytes) of the compressed data record. The out_length argument is the address of a word into which DCX$COMPRESS_DATA returns the length of the compressed data record.

Description

The DCX$COMPRESS_DATA routine compresses a data record. Call this routine for each data record to be compressed. As you compress each record, write the compressed record to the file containing the compression/expansion map. For each record, write the length of the record and substring string containing the record to the same file. See the COMPRESS DATA section in Example 7.1, “Compressing a File in a VSI Fortran Program”.

Condition Values Returned

This routine also returns any condition values returned by LIB$ANALYZE_SDESC_R2 and LIB$SCOPY_R_DX.

Format

DCX$COMPRESS_DONE context

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Argument

Value identifying the data stream that DCX$COMPRESS_DONE deletes. The context argument is the address of a longword containing this value. DCX$COMPRESS_INIT writes the value into the context argument; you should not modify its value. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.

Description

The DCX$COMPRESS_DONE routine deletes the context area and sets the context variable to zero, undoing the work of the DCX$COMPRESS_INIT routine. Call DCX$COMPRESS_DONE when all data records have been compressed (using DCX$COMPRESS_DATA). After calling DCX$COMPRESS_DONE, call LIB$FREE_VM to free the virtual memory that DCX$MAKE_MAP used for the compression/expansion function.

Condition Values Returned

This routine also returns any condition values returned by LIB$FREE_VM.

Format

DCX$COMPRESS_INIT context ,map

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

Value identifying the data stream that DCX$COMPRESS_INIT initializes. The context argument is the address of a longword containing this value. You should not modify the context value after DCX$COMPRESS_INIT initializes it. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.

The function created by DCX$MAKE_MAP. The map argument is the address of the compression/expansion function's virtual address.

The map argument must remain at this address until data compression is completed and the context is deleted by means of a call to DCX$COMPRESS_DONE.

Description

The DCX$COMPRESS_INIT routine initializes the context area for the compression of data records.

Call the DCX$COMPRESS_INIT routine after calling the DCX$ANALYZE_DONE routine.

Condition Values Returned

This routine also returns any condition values returned by LIB$GET_VM and LIB$FREE_VM.

Format

DCX$EXPAND_DATA context ,in_rec ,out_rec [,out_length]

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

Value identifying the data stream that DCX$EXPAND_DATA expands. The context argument is the address of a longword containing this value. DCX$EXPAND_INIT initializes this value; you should not modify it. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.

Data record to be expanded. The in_rec argument is the address of the descriptor of the data record string.

Data record that has been expanded. The out_rec argument is the address of the descriptor of the expanded record returned by DCX$EXPAND_DATA.

Length (in bytes) of the expanded data record. The out_length argument is the address of a word into which DCX$EXPAND_DATA returns the length of the expanded data record.

Description

The DCX$EXPAND_DATA routine expands (or restores) a compressed data record to its original state. Call this routine for each data record to be expanded.

Condition Values Returned

This routine also returns any condition values returned by LIB$ANALYZE_SDESC_R2 and LIB$SCOPY_R_DX.

Format

DCX$EXPAND_DONE context

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Argument

Value identifying the data stream that DCX$EXPAND_DONE deletes. The context argument is the address of a longword containing this value. DCX$EXPAND_INIT initializes this value; you should not modify it. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.

Description

The DCX$EXPAND_DONE routine deletes the context area and sets the context variable to zero, thus undoing the work of the DCX$EXPAND_INIT routine. Call DCX$EXPAND_DONE when all data records have been expanded (using DCX$EXPAND_DATA).

Condition Values Returned

This routine also returns any condition values returned by LIB$FREE_VM.

Format

DCX$EXPAND_INIT context ,map

Returns

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

Value identifying the data stream that DCX$EXPAND_INIT initializes. The context argument is the address of a longword containing this value. After DCX$EXPAND_INIT initializes this context value, you should not modify it. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.