OpenVMS RTL Library (LIB$) Manual

Document revision date: 19 July 1999

OpenVMS RTL Library (LIB$) Manual

Contents

Index

LIB$DEC_OVER

The Enable or Disable Decimal Overflow Detection routine enables or disables decimal overflow detection for the calling routine activation. The previous decimal overflow setting is returned.

Note
No support for arguments passed by 64-bit address reference or for use of 64-bit descriptors, if applicable, is planned for this routine.

This routine is available on OpenVMS Alpha systems in translated form and is applicable to translated VAX images only.

Format

LIB$DEC_OVER new-setting

RETURNS

OpenVMS usage: longword_unsigned

type: longword integer (unsigned)

access: write only

mechanism: by value

The old decimal overflow enable setting (the previous contents of SF$W_PSW[PSW$V_DV] in the caller's frame).

Argument

new-setting

OpenVMS usage: longword_unsigned

type: longword (unsigned)

access: read only

mechanism: by reference

New decimal overflow enable setting. The new-setting argument is the address of an unsigned longword that contains the new decimal overflow enable setting. Bit 0 set to 1 means enable; bit 0 set to 0 means disable.

Description

The caller's stack frame is modified by this routine.
A call to LIB$DEC_OVER affects only the current routine activation and does not affect any of its callers or any routines that it may call. However, the setting does remain in effect for any routines that are subsequently entered through a JSB entry point.

Example


DECOVF: ROUTINE OPTIONS (MAIN); DECLARE LIB$DEC_OVER ENTRY (FIXED BINARY (7)) /* Address of byte for /* enable/disable /* setting / RETURNS (FIXED BINARY (31)); / Old setting / DECLARE DISABLE FIXED BINARY (7) INITIAL (0) STATIC READONLY; DECLARE RESULT FIXED BINARY (31); DECLARE (A,B) FIXED DECIMAL (4,2); ON FIXEDOVERFLOW PUT SKIP LIST ('Overflow'); RESULT = LIB$DEC_OVER (DISABLE); / Disable recognition of decimal /* overflow in this block / A = 99.99; B = A + 2; PUT SKIP LIST ('In MAIN'); BEGIN; B = A + 2; PUT LIST ('In BEGIN block'); CALL Q; Q: ROUTINE; B = A + 2; PUT LIST ('In Q'); END Q; END / Begin */; END DECOVF;

DECOVF: ROUTINE OPTIONS (MAIN); 
 
DECLARE LIB$DEC_OVER ENTRY (FIXED BINARY (7))   /* Address of byte for 
                                                /*  enable/disable 
                                                /*  setting             */ 
        RETURNS (FIXED BINARY (31));            /* Old setting          */ 
 
DECLARE DISABLE FIXED BINARY (7) INITIAL (0) STATIC READONLY; 
DECLARE RESULT FIXED BINARY (31); 
DECLARE (A,B) FIXED DECIMAL (4,2); 
 
ON FIXEDOVERFLOW PUT SKIP LIST ('Overflow'); 
 
RESULT = LIB$DEC_OVER (DISABLE);        /* Disable recognition of decimal 
                                        /* overflow in this block       */ 
A = 99.99; 
B = A + 2; 
PUT SKIP LIST ('In MAIN'); 
        BEGIN; 
        B = A + 2; 
        PUT LIST ('In BEGIN block'); 
        CALL Q; 
                Q: ROUTINE; 
                B = A + 2; 
                PUT LIST ('In Q'); 
                END Q; 
        END /* Begin */; 
END DECOVF;

This PL/I program shows how to use LIB$DEC_OVER to enable or disable the detection of decimal overflow. Note that in PL/I, disabling decimal overflow using this routine causes the condition to be disabled only in the current block; descendent blocks will enable the condition unless this routine is called in each block.

LIB$DELETE_FILE

The Delete One or More Files routine deletes one or more files. The specification of the files to be deleted may include wildcards.
LIB$DELETE_FILE is similar in function to the DCL command DELETE.

Format

LIB$DELETE_FILE filespec [,default-filespec] [,related-filespec] [,user-success-procedure] [,user-error-procedure] [,user-confirm-procedure] [,user-specified-argument] [,resultant-name] [,file-scan-context] [,flags]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

String containing the OpenVMS Record Management Services (RMS) file specification of the files to be deleted. The filespec argument is the address of a descriptor pointing to the file specification. If the specification includes wildcards, each file that matches the specification is deleted. The string must not contain more than 255 characters. Any string class is supported.
On Alpha systems, set the LIB$M_FIL_LONG_NAMES bit in the flags argument for strings longer than 255 characters in length.
default-filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Default file specification of the files to be deleted. The default-filespec argument is the address of a descriptor pointing to the default file specification. This is an optional argument; if the argument is omitted, the default is the null string. Any string class is supported.
See the OpenVMS Record Management Services Reference Manual for information about default file specifications.
related-filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

Related file specification of the files to be deleted. The related-filespec argument is the address of a descriptor pointing to the related file specification. Any string class is supported. This is an optional argument; if the argument is omitted, the default is the null string.
Input file parsing is used. See the OpenVMS Record Management Services Reference Manual for information on related file specifications and input file parsing.
The related file specification is useful when you are processing lists of file specifications. Unspecified portions of the file specification are inherited from the last file processed.
user-success-procedure

OpenVMS usage: procedure

type: procedure value

access: function call (before return)

mechanism: by value

User-supplied success routine that LIB$DELETE_FILE calls after it successfully deletes a file.
The success routine can be used to display a log of the files that were deleted. For more information on the success routine, see Call Format for a Success Routine in the Description section.
user-error-procedure

OpenVMS usage: procedure

type: procedure value

access: function call (before return)

mechanism: by value

User-supplied error routine that LIB$DELETE_FILE calls when it detects an error.
The error routine returns a success/fail value that LIB$DELETE_FILE uses to determine if more files should be processed. For more information on the error routine, see Call Format for an Error Routine in the Description section.
user-confirm-procedure

OpenVMS usage: procedure

type: procedure value

access: function call (before return)

mechanism: by value

User-supplied confirm routine that LIB$DELETE_FILE calls before each file is deleted. The value returned by the confirm routine determines whether or not the file will be deleted. The confirm routine can be used to select specific files for deletion based on criteria such as expiration date, size, and so on. For more information about the confirm routine, see Call Format for a Confirm Routine in the Description section.
user-specified-argument

OpenVMS usage: user_arg

type: longword (unsigned)

access: read only

mechanism: by value

User-supplied argument that LIB$DELETE_FILE passes to the error, success, and confirm routines each time they are called. Whatever mechanism is used to pass user-specified-argument to LIB$DELETE_FILE is also used to pass it to the routines. This is an optional argument; if the argument is omitted, zero is passed by value.
resultant-name

OpenVMS usage: char_string

type: character string

access: write only

mechanism: by descriptor

String into which LIB$DELETE_FILE writes the RMS resultant file specification of the last file processed. The resultant-name argument is the address of a descriptor pointing to the resultant name.
If present, resultant-name is used to store the file specification passed to the user-supplied routines, instead of a default class S, type T string. Therefore, this argument should be specified when the user-supplied routines are used and those routines require a descriptor type other than class S, type T. Any string class is supported.
If you specify one or more of the user-supplied action routines, the descriptor used to pass resultant-name must be:

Of the same class as the descriptor required by the filespec argument of any action routines. For example, VAX Ada requires a class SB descriptor for string arguments to Ada routines but will use a class A descriptor by default when calling external routines. Refer to your language manual to determine the proper descriptor class to use.
(Alpha only) Of the same form as the descriptor required by the filespec argument of all action routines. For example, if the filespec argument of an action routine uses a 64-bit descriptor, then the resultant-name argument must also use a 64-bit descriptor.

file-scan-context

OpenVMS usage: context

type: longword (unsigned)

access: modify

mechanism: by reference

Context for deleting a list of file specifications. The file-scan-context argument is the address of a longword containing the context value.
You must initialize the file scan context to zero before the first of a series of calls to LIB$DELETE_FILE. LIB$FILE_SCAN uses this context to retain the file context for multiple input files. You must specify this context only when you are dealing with multiple input files, as the DCL command DELETE does. You may deallocate the context allocated by LIB$FILE_SCAN by calling LIB$FILE_SCAN_END after all calls to LIB$DELETE_FILE have been completed.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by reference

User flags. The flags argument is the address of an unsigned longword containing the user flags.
The flag bits and their corresponding symbols are described in the following table:

Bit Symbol Description

0 Reserved to Compaq.

1 Reserved to Compaq.

2 LIB$M_FIL_LONG_NAMES (Alpha only) If set, LIB$DELETE_FILE can process file names with a maximum length of NAML$C_MAXRSS. If clear, LIB$DELETE_FILE can process file specifications with a maximum length of 255 (default).

Bit	Symbol	Description
0		Reserved to Compaq.
1		Reserved to Compaq.
2	LIB$M_FIL_LONG_NAMES	(Alpha only) If set, LIB$DELETE_FILE can process file names with a maximum length of NAML$C_MAXRSS. If clear, LIB$DELETE_FILE can process file specifications with a maximum length of 255 (default).

Description

This Description section is divided into the following parts:

Call Format for a Success Routine
Call Format for an Error Routine
Call Format for a Confirm Routine

Call Format for a Success Routine

The success routine is called only if the user-success-procedure argument was specified in the LIB$DELETE_FILE argument list.
The calling format of a success routine is as follows:
user-success-procedure filespec [,user-specified-argument]
filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

RMS resultant file specification of the file being deleted. The filespec argument is the address of a descriptor pointing to the file specification. If the resultant-name argument was specified, it is used to pass the string to the success routine. Otherwise, a class S, type T string is passed. Any string class is supported.
On Alpha systems, the descriptor specified by each of the action routines for the filespec argument and the descriptor specified by the LIB$DELETE_FILE resultant-name argument, if any, must be of the same form. They must all be 32-bit descriptors or all 64-bit descriptors. If you do not specify a resultant-name argument, then the filespec argument must use a 32-bit descriptor.
user-specified-argument

OpenVMS usage: user_arg

type: longword (unsigned)

access: read only

mechanism: unspecified

Value of user-specified-argument passed by LIB$DELETE_FILE to the success routine. The same passing mechanism that was used to pass user-specified-argument to LIB$DELETE_FILE is used by LIB$DELETE_FILE to pass user-specified-argument to the success routine. This is an optional argument.
Call Format for an Error Routine

The error routine is called only if the user-error-procedure argument was specified in the LIB$DELETE_FILE argument list.
The calling format of an error routine is as follows:
user-error-procedure filespec ,rms-sts ,rms-stv ,error-source [,user-specified-argument]
filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

String containing the RMS resultant file specification of the file being deleted. If resultant-name was specified, it is used to pass the string to the error routine. Otherwise, a class S, type T string is passed. Any string class is supported.
On Alpha systems, the descriptor specified by each of the action routines for the filespec argument and the descriptor specified by the LIB$DELETE_FILE resultant-name argument, if any, must be of the same form. They must all be 32-bit descriptors or all 64-bit descriptors. If you specify no resultant-name argument, then the filespec argument must use a 32-bit descriptor.
rms-sts

OpenVMS usage: cond_value

type: longword (unsigned)

access: read only

mechanism: by reference

Primary condition code (FAB$L_STS) that describes the error that occurred. The rms-sts argument is the address of an unsigned longword that contains the primary condition code.
rms-stv

OpenVMS usage: cond_value

type: longword (unsigned)

access: read only

mechanism: by reference

Secondary condition code (FAB$L_STV) that describes the error that occurred. The rms-stv argument is the address of an unsigned longword that contains the secondary condition code.
error-source

OpenVMS usage: longword_signed

type: longword integer (signed)

access: read only

mechanism: by reference

Integer code that indicates the point at which the error was found. The error-source argument is the address of a longword integer containing the code of the error source.
Possible values for the error code are as follows:

0 Error searching for file specification

1 Error deleting file

user-specified-argument

OpenVMS usage: user_arg

type: unspecified

access: read only

mechanism: unspecified

Value passed to LIB$DELETE_FILE that is then passed to user-error-procedure using the same passing mechanism that was used to pass it to LIB$DELETE_FILE. This is an optional argument.
If the error routine returns a success status (bit 0 set), then LIB$DELETE_FILE continues processing files. If a failure status (bit 0 clear) is returned, then processing ceases immediately, and LIB$DELETE_FILE returns with the error status.
If the user-error-procedure argument is not specified, LIB$DELETE_FILE returns to its caller the most severe error status encountered while deleting the files. If the error routine is called for an error, the success status LIB$_ERRROUCAL is returned.
The error routine is not called for errors related to string copying.
Call Format for a Confirm Routine

The confirm routine is called only if the user-confirm-procedure argument was specified in the call to LIB$DELETE_FILE.
The calling format of the confirm routine is as follows:
user-confirm-procedure filespec ,fab [,user-specified-argument]
filespec

OpenVMS usage: char_string

type: character string

access: read only

mechanism: by descriptor

RMS resultant file specification of the file to be deleted. The filespec argument is the address of a descriptor pointing to the file specification.
If resultant-name was specified, it is used to pass the string to the confirm routine. Otherwise, a class S, type T string is passed. Any string class is supported.
On Alpha systems, the descriptor specified by each of the action routines for the filespec argument and the descriptor specified by the LIB$DELETE_FILE resultant-name argument, if any, must be of the same form. They must all be 32-bit descriptors or all 64-bit descriptors. If you do not specify a resultant-name argument, then the filespec argument must use a 32-bit descriptor.
fab

OpenVMS usage: fab

type: unspecified

access: read only

mechanism: by reference

RMS file access block (FAB) that describes the file being deleted. Your program may perform an RMS $OPEN on the FAB to obtain file attributes to determine whether the file should be deleted, but it must close the file with $CLOSE before returning to LIB$DELETE_FILE.
On Alpha systems, if the LIB$M_FIL_LONG_NAMES FLAGS is set, the FAB references a NAML block rather than a NAM block. The NAML block supports the use of long file names with a maximum length of NAML$C_MAXRSS. See the OpenVMS Record Management Services Reference Manual for information on NAML blocks.
user-specified-argument

OpenVMS usage: user_arg

type: unspecified

access: read only

mechanism: unspecified

The value of the user-specified-argument argument that LIB$DELETE_FILE passes to the confirm routine using the same passing mechanism that was used to pass it to LIB$DELETE_FILE. This is an optional argument.
If confirm routine returns a success status (bit 0 set), the file is then deleted; otherwise, the file is not deleted.

Condition Values Returned

SS$_NORMAL Routine successfully completed.

LIB$_ERRROUCAL Success, but an error routine was called. A file error was encountered, but the error routine was called to handle the condition.

LIB$INVARG Invalid argument. The flags argument has one or more undefined bits set.

LIB$_INVFILSPE Invalid file specification. Filespec or default-filespec is longer than 255 characters.

LIB$_INVSTRDES Invalid string descriptor. The descriptor for a string argument was not a valid string descriptor.

LIB$_WRONUMARG Wrong number of arguments. An incorrect number of arguments was passed to LIB$DELETE_FILE.

Any condition value returned by LIB$SCOPY_xxx except those condition values specifying truncation errors.

Any condition value returned by RMS. If user-error-procedure is not specified, this is the most severe of the RMS errors encountered while deleting the files.

Example


PROGRAM DELETE_EXAMPLE(INPUT, OUTPUT); {+} { Declare external function LIB$DELETE_FILE. Throughout this { example, the user-arg argument is not used. {-} FUNCTION LIB$DELETE_FILE( FILESPEC: VARYING [A] OF CHAR; DEFAULT_FILESPEC: VARYING [B] OF CHAR; REL_FILESPEC : VARYING [D] OF CHAR; %IMMED [UNBOUND] ROUTINE SUCCESS_ROUTINE (FILESPEC : VARYING [A] OF CHAR) := %IMMED 0; %IMMED [UNBOUND] FUNCTION ERROR_ROUTINE (FILESPEC : VARYING [A] OF CHAR; RMS_STS, RMS_STV : INTEGER) : BOOLEAN := %IMMED 0; %IMMED [UNBOUND] FUNCTION CONFIRM_ROUTINE (FILESPEC: VARYING [A] OF CHAR): BOOLEAN := %IMMED 0; VAR USER_ARG : [UNSAFE] INTEGER := %IMMED 0; VAR RESULT_NAME : VARYING [C] OF CHAR := %IMMED 0 ) : INTEGER; EXTERN; {+} { Declare a routine which will display the names of the files { as they are deleted. {-} ROUTINE LOG_ROUTINE(FILESPEC : VARYING [A] OF CHAR); BEGIN WRITELN('File ', FILESPEC, ' successfully deleted'); END; {+} { Declare a routine which will notify the user that an error { occurred. {-} FUNCTION ERR_ROUTINE(FILESPEC: VARYING [A] OF CHAR; RMS_STS, RMS_STV: INTEGER): BOOLEAN; BEGIN WRITELN('Delete of ', FILESPEC, ' failed ', HEX(RMS_STS)); ERR_ROUTINE := TRUE; END; {+} { Declare a routine which checks to see if the file should be { deleted. If the filename contains the string 'XYZ', then it is { deleted. {-} FUNCTION CONFIRM_ROUTINE( FILESPEC: VARYING [A] OF CHAR): BOOLEAN; BEGIN IF INDEX(FILESPEC, 'XYZ') <> 0 THEN CONFIRM_ROUTINE := TRUE ELSE CONFIRM_ROUTINE := FALSE; END; {+} { The main program begins here. {-} VAR FILES_TO_DELETE, RESULTANT_NAME : VARYING [255] OF CHAR; RET_STATUS : INTEGER; BEGIN WRITE ('Files to delete: '); READLN(FILES_TO_DELETE); RET_STATUS := LIB$DELETE_FILE( FILES_TO_DELETE, '*;', '', LOG_ROUTINE, ERR_ROUTINE, CONFIRM_ROUTINE,,RESULTANT_NAME); IF NOT ODD(RET_STATUS) THEN WRITELN('Delete failed. The error was ', HEX(RET_STATUS)); END.

PROGRAM DELETE_EXAMPLE(INPUT, OUTPUT); 
 
{+} 
{ Declare external function LIB$DELETE_FILE.   Throughout this 
{ example, the user-arg argument is not used. 
{-} 
 
FUNCTION LIB$DELETE_FILE( 
        FILESPEC: VARYING [A] OF CHAR; 
        DEFAULT_FILESPEC: VARYING [B] OF CHAR; 
        REL_FILESPEC : VARYING [D] OF CHAR; 
        %IMMED [UNBOUND] ROUTINE SUCCESS_ROUTINE 
            (FILESPEC : VARYING [A] OF CHAR) := %IMMED 0; 
        %IMMED [UNBOUND] FUNCTION ERROR_ROUTINE 
            (FILESPEC : VARYING [A] OF CHAR; RMS_STS, RMS_STV : INTEGER) 
            : BOOLEAN := %IMMED 0; 
        %IMMED [UNBOUND] FUNCTION CONFIRM_ROUTINE 
            (FILESPEC: VARYING [A] OF CHAR): BOOLEAN := %IMMED 0; 
        VAR USER_ARG : [UNSAFE] INTEGER := %IMMED 0; 
        VAR RESULT_NAME : VARYING [C] OF CHAR := %IMMED 0 
    ) : INTEGER; EXTERN; 
 
 
{+} 
{ Declare a routine which will display the names of the files 
{ as they are deleted. 
{-} 
 
ROUTINE LOG_ROUTINE(FILESPEC : VARYING [A] OF CHAR); 
    BEGIN 
        WRITELN('File ', FILESPEC, ' successfully deleted'); 
    END; 
 
 
{+} 
{ Declare a routine which will notify the user that an error 
{ occurred. 
{-} 
 
FUNCTION ERR_ROUTINE(FILESPEC: VARYING [A] OF CHAR; 
        RMS_STS, RMS_STV: INTEGER): BOOLEAN; 
    BEGIN 
        WRITELN('Delete of ', FILESPEC, ' failed ', HEX(RMS_STS)); 
        ERR_ROUTINE := TRUE; 
    END; 
 
 
{+} 
{ Declare a routine which checks to see if the file should be 
{ deleted.  If the filename contains the string 'XYZ', then it is 
{ deleted. 
{-} 
 
FUNCTION CONFIRM_ROUTINE( FILESPEC: VARYING [A] OF CHAR): BOOLEAN; 
    BEGIN 
        IF INDEX(FILESPEC, 'XYZ') <> 0 
        THEN 
            CONFIRM_ROUTINE := TRUE 
        ELSE 
            CONFIRM_ROUTINE := FALSE; 
    END; 
 
{+} 
{ The main program begins here. 
{-} 
 
VAR 
    FILES_TO_DELETE,  RESULTANT_NAME : VARYING [255] OF CHAR; 
    RET_STATUS : INTEGER; 
 
BEGIN 
    WRITE ('Files to delete: '); 
    READLN(FILES_TO_DELETE); 
    RET_STATUS := LIB$DELETE_FILE( 
        FILES_TO_DELETE, '*;', '', LOG_ROUTINE, ERR_ROUTINE, 
                CONFIRM_ROUTINE,,RESULTANT_NAME); 
    IF NOT ODD(RET_STATUS) 
    THEN 
        WRITELN('Delete failed.  The error was ', HEX(RET_STATUS)); 
END.

This Pascal program prompts the user for file specifications of files to be deleted. Of those, it deletes only files that contain the string XYZ somewhere in their resultant file specification. The names of deleted files are displayed.

Contents

Index

privacy and legal statement

5932PRO_011.HTML

OpenVMS usage:	longword_unsigned
type:	longword integer (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

OpenVMS usage:	procedure
type:	procedure value
access:	function call (before return)
mechanism:	by value

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	longword_signed
type:	longword integer (signed)
access:	read only
mechanism:	by reference

OpenVMS usage:	fab
type:	unspecified
access:	read only
mechanism:	by reference

SS$_NORMAL	Routine successfully completed.
LIB$_ERRROUCAL	Success, but an error routine was called. A file error was encountered, but the error routine was called to handle the condition.
LIB$INVARG	Invalid argument. The flags argument has one or more undefined bits set.
LIB$_INVFILSPE	Invalid file specification. Filespec or default-filespec is longer than 255 characters.
LIB$_INVSTRDES	Invalid string descriptor. The descriptor for a string argument was not a valid string descriptor.
LIB$_WRONUMARG	Wrong number of arguments. An incorrect number of arguments was passed to LIB$DELETE_FILE.