| 
       
          Document revision date: 19 July 1999
      
     | 
  
 
  
    
![[Compaq]](../../images/compaq.gif)  | 
    
       
 
 
 
 
      
     | 
  
 
  
    
 
     | 
  
 
 
 
 
OpenVMS RTL Library (LIB$) Manual
LIB$WAIT
The Wait a Specified Period of Time routine places the current process 
into hibernation for the number of seconds specified in its argument.
Format
LIB$WAIT seconds [,flags] [,float-type] 
RETURNS
  
    | OpenVMS usage:  | 
    cond_value | 
  
  
    | type:  | 
    longword (unsigned) | 
  
  
    | access:  | 
    write only | 
  
  
    | mechanism: | 
    by value | 
  
Arguments
seconds
  
    | OpenVMS usage:  | 
    floating_point | 
  
  
    | type:  | 
    F_floating | 
  
  
    | access:  | 
    read only | 
  
  
    | mechanism: | 
    by reference | 
  
The number of seconds to wait. The seconds argument 
contains the address of an F-floating number that is this number.
The value is rounded to the nearest hundredth-second before use. 
Seconds must be between 0.0 and 100,000.0.
flags
  
    | OpenVMS usage:  | 
    mask_longword | 
  
  
    | type:  | 
    longword (unsigned) | 
  
  
    | access:  | 
    read only | 
  
  
    | mechanism: | 
    by reference | 
  
Control flags. The flags argument is the address of a 
longword integer that contains the control flags. The following flag is 
defined:
  
    | Bit  | 
    Value  | 
    Description  | 
  
  
    | 
      0
     | 
    
      LIB$K_NOWAKE
     | 
    
      LIB$WAIT will not wake in the case of an interrupt.
     | 
  
This is an optional argument. If omitted, the default is 0, and 
LIB$WAIT will wake in the case of an interrupt.
float-type
  
    | OpenVMS usage:  | 
    longword-unsigned | 
  
  
    | type:  | 
    longword (unsigned) | 
  
  
    | access:  | 
    read only | 
  
  
    | mechanism: | 
    by reference | 
  
Float type. The float-type argument is the address of 
a longword integer that determines the floating-point type of the 
seconds argument. Use one of the following symbols:
  
    | Symbol  | 
    Value  | 
    Floating-Point Type  | 
  
  
    | 
      LIB$K_VAX_F
     | 
    
      0
     | 
    
      F_floating
     | 
  
  
    | 
      LIB$K_VAX_D
     | 
    
      1
     | 
    
      D_floating
     | 
  
  
    | 
      LIB$K_VAX_G
     | 
    
      2
     | 
    
      G_floating
     | 
  
  
    | 
      LIB$K_VAX_H
     | 
    
      3
     | 
    
      H_floating
     | 
  
  
    | 
      LIB$K_IEEE_S
     | 
    
      4
     | 
    
      IEEE_S_floating
     | 
  
  
    | 
      LIB$K_IEEE_T
     | 
    
      5
     | 
    
      IEEE_T_floating
     | 
  
This is an optional argument. If omitted, the default is F_floating. 
F_floating is the required float-type when LIB$WAIT is 
called from a module written in a language that prototypes functions.
Description
LIB$WAIT rounds the value specified by seconds to the nearest 
hundredth-second, uses the $SCHDWK system service to schedule a wakeup 
for that interval, and then issues the $HIBER system service to 
hibernate until the wakeup occurs.
Because of other system activity, the length of time that the process 
actually waits may be somewhat longer than what was specified by 
seconds.
The process hibernates in the caller's access mode; therefore, 
asynchronous system traps (ASTs) may be delivered while the process is 
hibernating. However, if the process hibernates at AST level, further 
ASTs can not be delivered.
When the LIB$K_NOWAIT control flag is used, LIB$WAIT makes use of the 
$SETIMR system service to schedule the wakeup, and then issues a $SYNCH 
system service call to check for the completion status. In this case, 
LIB$WAIT will not be interrupted by $WAKE. Use LIB$K_NOWAKE when it is 
necessary for the wait to be completed without interruption.
  Note 
The NOWAKE option makes use of the $SETIMR and $SYNCH system services. 
Because use of these services requires that an AST be delivered, you 
should not use LIB$WAIT with the LIB$K_NOWAKE control flag at AST 
level. 
     | 
  
See the OpenVMS System Services Reference Manual for more information.
Condition Values Returned
  
    | 
      SS$_NORMAL
     | 
    
      Routine successfully completed.
     | 
  
  
    | 
      LIB$_INVARG
     | 
    
      Invalid argument. The value of
      seconds was less than 0 or greater than 100,000.0
     | 
  
  
    | 
      LIB$_WRONUMARG
     | 
    
      Wrong number of arguments. An incorrect number of arguments was passed 
      to LIB$WAIT.
     | 
  
Any condition values returned by the $SCHDWK or SETIMR system services, 
or by the RTL routine LIB$CVT_FTOF.
Example
  
     | 
  
    
       
      
IDENTIFICATION DIVISION. 
PROGRAM-ID. SAMPLE. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
01    DELAY COMP-1. 
ROUTINE DIVISION. 
START-SAMPLE. 
    MOVE 3.5 TO DELAY. 
    CALL "LIB$WAIT" 
    USING BY REFERENCE DELAY. 
    STOP RUN. 
 
      
      
     | 
  
This COBOL program demonstrates the use of LIB$WAIT. When run, it waits 
for 3.5 seconds and then exits.
Part 3
CVT$ Reference Section
This part provides a detailed discussion of the routines provided by 
the OpenVMS RTL (CVT$) Facility.
CVT$CONVERT_FLOAT
The Convert Floating-Point Data Type routine provides a simplified 
options-interface for converting a floating-point data type to another 
supported floating-point data type.
Format
CVT$CONVERT_FLOAT input_value, input_type_code, output_value, 
output_type_code, options 
RETURNS
  
    | OpenVMS usage:  | 
    cond_value | 
  
  
    | type:  | 
    longword (unsigned) | 
  
  
    | access:  | 
    write only | 
  
  
    | mechanism: | 
    by value | 
  
Arguments
input_value
  
    | OpenVMS usage:  | 
    varying_arg | 
  
  
    | type:  | 
    unspecified | 
  
  
    | access:  | 
    read only | 
  
  
    | mechanism: | 
    by reference | 
  
The address of a data area containing a floating-point number that is 
to be converted. The input_value argument may contain 
floating-point data in F_Floating, D_Floating, G_Floating, H_Floating, 
IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, IBM_Long_Floating, 
IBM_Short_Floating, or CRAY_Floating format. The value of the 
input_type_code argument determines the format and 
size of the input_value argument.
input_type_code
  
    | OpenVMS usage:  | 
    longword_unsigned | 
  
  
    | type:  | 
    longword (unsigned) | 
  
  
    | access:  | 
    read only | 
  
  
    | mechanism: | 
    by value | 
  
The value of a longword bit mask specifying the type of floating-point 
data being passed in the input_value argument. Valid 
type codes are:
  
    | input_type_code  | 
    Format  | 
    Size in Bytes  | 
  
  
    | 
      CVT$K_VAX_F
     | 
    
      F_Floating
     | 
    
      4
     | 
  
  
    | 
      CVT$K_VAX_D
     | 
    
      D_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_VAX_G
     | 
    
      G_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_VAX_H
     | 
    
      H_Floating
     | 
    
      16
     | 
  
  
    | 
      CVT$K_IEEE_S
     | 
    
      IEEE_S_Floating
     | 
    
      4
     | 
  
  
    | 
      CVT$K_IEEE_T
     | 
    
      IEEE_T_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_IEEE_X
     | 
    
      IEEE_X_Floating
     | 
    
      16
     | 
  
  
    | 
      CVT$K_IBM_LONG
     | 
    
      IBM_Long_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_IBM_SHORT
     | 
    
      IBM_Short_Floating
     | 
    
      4
     | 
  
  
    | 
      CVT$K_CRAY
     | 
    
      CRAY_Floating
     | 
    
      8
     | 
  
Declarations for the input_type_code argument are in 
the $CVTDEF module found in the system symbol libraries.
output_value
  
    | OpenVMS usage:  | 
    varying_arg | 
  
  
    | type:  | 
    unspecified | 
  
  
    | access:  | 
    write only | 
  
  
    | mechanism: | 
    by reference | 
  
The address of a data area that receives the converted floating-point 
number. The output_value argument can contain 
floating-point data in F_Floating, D_Floating, G_Floating, H_Floating, 
IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, IBM_Long_Floating, 
IBM_Short_Floating, or CRAY_Floating format. The value of the 
output_type_code argument determines the size and 
format of the data placed into the output_value 
argument.
output_type_code
  
    | OpenVMS usage:  | 
    longword_unsigned  | 
  
  
    | type:  | 
    longword (unsigned) | 
  
  
    | access:  | 
    read only | 
  
  
    | mechanism: | 
    by value | 
  
The value of a longword bit mask specifying the type of floating-point 
data that the input_value argument will be converted 
into and returned in the output_value argument. Valid 
type codes are:
  
    | output_type_code  | 
    Format  | 
    Size in Bytes  | 
  
  
    | 
      CVT$K_VAX_F
     | 
    
      F_Floating
     | 
    
      4
     | 
  
  
    | 
      CVT$K_VAX_D
     | 
    
      D_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_VAX_G
     | 
    
      G_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_VAX_H
     | 
    
      H_Floating
     | 
    
      16
     | 
  
  
    | 
      CVT$K_IEEE_S
     | 
    
      IEEE_S_Floating
     | 
    
      4
     | 
  
  
    | 
      CVT$K_IEEE_T
     | 
    
      IEEE_T_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_IEEE_X
     | 
    
      IEEE_X_Floating
     | 
    
      16
     | 
  
  
    | 
      CVT$K_IBM_LONG
     | 
    
      IBM_Long_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_IBM_SHORT
     | 
    
      IBM_Short_Floating
     | 
    
      4
     | 
  
  
    | 
      CVT$K_CRAY
     | 
    
      CRAY_Floating
     | 
    
      8
     | 
  
Declarations for the output_type_code argument are in 
the $CVTDEF module found in the system symbol libraries.
options
  
    | OpenVMS usage:  | 
    mask_longword | 
  
  
    | type:  | 
    longword (unsigned) | 
  
  
    | access:  | 
    read only | 
  
  
    | mechanism: | 
    by value | 
  
Conversion option specifier. The options argument is 
the address of a longword bit mask in which each option bit set causes 
the corresponding option to be used during the conversion.
The following options can be specified using the 
options argument:
  
    | Option  | 
    Description  | 
  
  
    | 
      CVT$M_ROUND_TO_NEAREST
     | 
    
      The default rounding option for conversions to IEEE data types. This 
      IEEE Std. 754 rounding mode results in the representable output value 
      nearest to the infinitely precise result. If the two nearest 
      representable values are equally near, the one whose least significant 
      bit is 0 is the result.
     | 
  
  
    | 
      CVT$M_VAX_ROUNDING
     | 
    
      The default rounding option for conversions to non-IEEE data types. 
      Performs "traditional" style rounding. This mode results in the 
      representable output value nearest to the infinitely precise result. If 
      the two nearest representable values are equally near, the output value 
      is the closest to either positive infinity or negative infinity, 
      depending on the sign of the input value.
     | 
  
  
    | 
      CVT$M_TRUNCATE
     | 
    
      Round the output value toward zero (truncate).
     | 
  
  
    | 
      CVT$M_ROUND_TO_POS
     | 
    
      Round the output value toward positive infinity.
     | 
  
  
    | 
      CVT$M_ROUND_TO_NEG
     | 
    
      Round the output value toward negative infinity.
     | 
  
  
    | 
      CVT$M_BIG_ENDIAN
     | 
    
      Interprets IEEE data types as Big Endian.
     | 
  
  
    | 
      CVT$M_ERR_UNDERFLOW
     | 
    
      Report underflow conditions as errors.
     | 
  
Declarations for the options argument are in the $CVTDEF module found 
in the system symbol libraries.
Description
CVT$CONVERT_FLOAT is a general-purpose, floating-point conversion 
routine that converts any input_type_code 
floating-point data type into any output_type_code 
floating-point data type. The conversion is subject to the options 
specified in the options argument.
  Note 
OpenVMS compilers do not support arithmetic operations for all of the 
above floating-point data types. Additional floating-point data types 
are supported by this routine for data conversion purposes only. 
     | 
  
Condition Values Returned
  
    | 
      CVT$_NORMAL
     | 
    
      Normal successful completion.
     | 
  
  
    | 
      CVT$_INPCONERR
     | 
    
      Input conversion error.
     | 
  
  
    | 
      CVT$_INVINPTYP
     | 
    
      Invalid input type code.
     | 
  
  
    | 
      CVT$_INVOPT
     | 
    
      Invalid option argument.
     | 
  
  
    | 
      CVT$_INVOUTTYP
     | 
    
      Invalid output type code.
     | 
  
  
    | 
      CVT$_INVVAL
     | 
    
      Input value was an invalid number or NaN.
     | 
  
  
    | 
      CVT$_NEGINF
     | 
    
      Input value was negative infinity.
     | 
  
  
    | 
      CVT$_OUTCONERR
     | 
    
      Output conversion error.
     | 
  
  
    | 
      CVT$_OVERFLOW
     | 
    
      Overflow detected during conversion.
     | 
  
  
    | 
      CVT$_POSINF
     | 
    
      Input value was positive infinity.
     | 
  
  
    | 
      CVT$_UNDERFLOW
     | 
    
      Underflow detected during conversion.
     | 
  
Return status values are in the $CVTMSG module found in the system 
symbol libraries.
Example
  
     | 
  
    
       
      
/* 
** =================================================================== 
** 
**  Example of CVT$CONVERT_FLOAT 
** 
** ------------------------------------------------------------------- 
** 
**  This example program reads IEEE T floating-point numbers from an 
**  input file, converts them to VAX D floating-point numbers and 
**  writes the result to an output file. 
** 
**  The input and output file names can be specified as the first and 
**  second arguments on the command line as follows: 
** 
**     $ EXAMPLE IEEE_T_INPUT_FILE.DAT VAX_D_OUTPUT_FILE.DAT 
** 
**  If the input or output files are not included on the command 
**  line then the program prompts the user for them. 
** 
** =================================================================== 
*/ 
#include <stdio.h> 
 
unsigned long CVT$CONVERT_FLOAT(void    *input_value, 
                                unsigned long input_type, 
                                void    *output_value, 
                                unsigned long output_type, 
                                unsigned long options); 
 
globalvalue CVT$K_VAX_D; 
globalvalue CVT$K_IEEE_T; 
globalvalue CVT$M_ROUND_TO_NEAREST; 
globalvalue CVT$_NORMAL; 
 
main(int argc, char *argv[]) 
 
{ 
 
  double        D_Float_number; 
  unsigned long IEEE_Double_number[2]; 
  unsigned long options; 
  char          in_filename[80]; 
  char          out_filename[80]; 
  FILE          *in_file, *out_file; 
  unsigned long ret_status; 
 
/* 
** Find out where we are going to get the data from.  
** First look at the first argument of the command line.  
** If nothing is there, then attempt to use IEEE_T_IN.DAT. 
** ================================================================= 
*/ 
if (argc == 1) 
{ 
  printf("Enter input data file: [IEEE_T_IN.DAT]: "); 
  if (gets(in_filename) == NULL) 
    exit(1); 
 
  if (strlen(in_filename) == 0)  
    strcpy(in_filename, "IEEE_T_IN.DAT"); 
}    
else 
  strcpy(in_filename, argv[1]); 
 
/* 
** Find out where we are going to put the output data. 
** First look at the second argument of the command line.  
** If nothing is there, then put it in VAX_D_OUT.DAT 
** ================================================================= 
*/ 
if (argc <= 2) 
{ 
  printf("Enter output data file: [VAX_D_OUT.DAT]: "); 
  if (gets(out_filename) == NULL) 
    exit(1); 
 
  if (strlen(out_filename) == 0)  
    strcpy(out_filename, "VAX_D_OUT.DAT"); 
}    
else 
  strcpy(out_filename, argv[2]); 
 
/* 
** Open the input and output files. 
** ----------------------------------------------------------------- 
*/ 
if ((in_file = fopen(in_filename, "r")) == NULL) 
{ 
  fprintf(stderr, "%s couldn't open file %s\n", argv[0], in_filename); 
  exit(1); 
} 
 
out_file = fopen(out_filename, "wb"); 
 
options     = CVT$M_ROUND_TO_NEAREST; 
ret_status  = CVT$_NORMAL; 
 
/* 
** Read in each number from the file, convert it, and write it to 
** the output file. 
** ================================================================= 
*/ 
while ((fread (&IEEE_Double_number[0], 
               sizeof(IEEE_Double_number), 
               1, 
               in_file) == 1) && 
       (ret_status == CVT$_NORMAL)) 
{ 
  ret_status = CVT$CONVERT_FLOAT(&IEEE_Double_number[0], CVT$K_IEEE_T, 
                                 &D_Float_number, CVT$K_VAX_D, 
                                 options); 
 
  if (ret_status == CVT$NORMAL) 
  { 
    fwrite(&D_Float_number, sizeof(D_Float_number), 1, out_file); 
    printf("Converted data: %lf.\n", D_Float_number); 
  } 
} 
fclose(in_file); 
fclose(out_file); 
 
if (ret_status == CVT$_NORMAL) 
  exit(1); 
else 
  exit(ret_status); 
} 
      
      
     | 
  
CVT$FTOF
The Convert Floating-Point Data Type routine converts floating-point 
data types to other supported floating-point data types and allows 
additional control over the converted results. CVT$FTOF functionality 
is also available on other platforms supported by Compaq.
Format
 status = CVT$FTOF input_value, input_type_code, output_value, 
output_type_code, options 
RETURNS
  
    | OpenVMS usage:  | 
    mask_longword | 
  
  
    | type:  | 
    longword (unsigned) | 
  
  
    | access:  | 
    write only | 
  
  
    | mechanism: | 
    by value | 
  
The status return value is an unsigned longword bit 
mask containing the condition codes raised by the function. CVT$FTOF 
returns CVT$K_NORMAL; otherwise, it sets one or more recoverable and 
unrecoverable conditions. Use the following condition names to 
determine which conditions are set:
  
    | Condition Name  | 
    Condition (always reported by default)  | 
  
  
    | 
      CVT$K_NORMAL
     | 
    
      Normal successful completion.
     | 
  
  
    | 
      CVT$M_INVALID_INPUT_TYPE
     | 
    
      Invalid input type code.
     | 
  
  
    | 
      CVT$M_INVALID_OUTPUT_TYPE
     | 
    
      Invalid output type code.
     | 
  
  
    | 
      CVT$M_INVALID_OPTION
     | 
    
      Invalid option argument.
     | 
  
  
    | Condition Name  | 
    Condition (reported only if the CVT$M_REPORT_ALL option is selected)  | 
  
  
    | 
      CVT$M_RESULT_INFINITE
     | 
    
      Conversion produced an infinite result.
      1
     | 
  
  
    | 
      CVT$M_RESULT_DENORMALIZED
     | 
    
      Conversion produced a denormalized result.
      1
     | 
  
  
    | 
      CVT$M_RESULT_OVERFLOW_RANGE
     | 
    
      Conversion yielded an exponent greater than 60000 (8).
      2
     | 
  
  
    | 
      CVT$M_RESULT_UNDERFLOW_RANGE
     | 
    
      Conversion yielded an exponent less than 20000 (8).
      2
     | 
  
  
    | 
      CVT$M_RESULT_UNNORMALIZED
     | 
    
      Conversion produced an unnormalized result.
      3
     | 
  
  
    | 
      CVT$M_RESULT_INVALID
     | 
    
      Conversion result is either ROP (reserved operand), NaN (not a number), 
      or closest equivalent. CRAY and IBM data types return 0.
      4
     | 
  
  
    | 
      CVT$M_RESULT_OVERFLOW
     | 
    
      Conversion resulted in overflow.
      4
     | 
  
  
    | 
      CVT$M_RESULT_UNDERFLOW
     | 
    
      Conversion resulted in underflow.
      4
     | 
  
  
    | 
      CVT$M_RESULT_INEXACT
     | 
    
      Conversion resulted in a loss of precision.
      4
     | 
  
1For IEEE data type conversions.
2For CRAY data type conversions.
3For IBM data type conversions.
4For all data type conversions.
Return status values are in the $CVTDEF module in the system symbol 
libraries.
Arguments
input_value
  
    | OpenVMS usage:  | 
    varying_arg | 
  
  
    | type:  | 
    unspecified | 
  
  
    | access:  | 
    read only | 
  
  
    | mechanism: | 
    by reference | 
  
The address of a data area containing a floating-point number to be 
converted. The number can be floating-point data in one of the 
following formats:
  
    | 
      F_Floating
     | 
    
      Big_Endian_IEEE_S_Floating
     | 
  
  
    | 
      D_Floating
     | 
    
      Big_Endian_IEEE_T_Floating
     | 
  
  
    | 
      G_Floating
     | 
    
      Big_Endian_IEEE_X_Floating
     | 
  
  
    | 
      H_Floating
     | 
    
      IBM_Long_Floating
     | 
  
  
    | 
      IEEE_S_Floating
     | 
    
      IBM_Short_Floating
     | 
  
  
    | 
      IEEE_T_Floating
     | 
    
      CRAY_Floating_Single
     | 
  
  
    | 
      IEEE_X_Floating
     | 
    
       
     | 
  
The value of the input_type_code argument determines 
the format and size of the input_value argument.
input_type_code
  
    | OpenVMS usage:  | 
    longword_unsigned | 
  
  
    | type:  | 
    longword (unsigned) | 
  
  
    | access:  | 
    read only | 
  
  
    | mechanism: | 
    by value | 
  
The value of a longword bit mask specifying the type of floating-point 
data being passed in the input_value argument. Valid 
type codes are:
  
    | Input_type_code  | 
    Format  | 
    Size in Bytes  | 
  
  
    | 
      CVT$K_VAX_F
     | 
    
      F_Floating
     | 
    
      4
     | 
  
  
    | 
      CVT$K_VAX_D
     | 
    
      D_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_VAX_G
     | 
    
      G_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_VAX_H
     | 
    
      H_Floating
     | 
    
      16
     | 
  
  
    | 
      CVT$K_IEEE_S
     | 
    
      IEEE_S_Floating
     | 
    
      4
     | 
  
  
    | 
      CVT$K_IEEE_T
     | 
    
      IEEE_T_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_IEEE_X
     | 
    
      IEEE_X_Floating
     | 
    
      16
     | 
  
  
    | 
      CVT$K_BIG_ENDIAN_IEEE_S
     | 
    
      Big_Endian_IEEE_S_Floating
     | 
    
      4
     | 
  
  
    | 
      CVT$K_BIG_ENDIAN_IEEE_T
     | 
    
      Big_Endian_IEEE_T_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_BIG_ENDIAN_IEEE_X
     | 
    
      Big_Endian_IEEE_X_Floating
     | 
    
      16
     | 
  
  
    | 
      CVT$K_IBM_LONG
     | 
    
      IBM_Long_Floating
     | 
    
      8
     | 
  
  
    | 
      CVT$K_IBM_SHORT
     | 
    
      IBM_Short_Floating
     | 
    
      4
     | 
  
  
    | 
      CVT$K_CRAY_SINGLE
     | 
    
      CRAY_Floating
     | 
    
      8
     |