VMS Help  —  RTL Routines
       The OpenVMS  Run-Time  Library  is  a  collection  of  procedures
       available  to  native  mode images  at run  time.   These library
       procedures are  common to  all native  mode images, regardless of
       the language processor used to compile or assemble the program.

1  –  CVT$

1.1  –  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

1.1.1  –  Returns

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

1.1.2  –  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:

                                                          Size in
    input_type_code          Format                       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:

                                                          Size in
    output_type_code         Format                       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_        The default rounding option for
    NEAREST                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.

1.2  –  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.

    Format

      status = CVT$FTOF  input_value, input_type_code, output_value,

                         output_type_code, options

1.2.1  –  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.

    Return status values are in the $CVTDEF module in the system
    symbol libraries.

1.2.2  –  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:

                                                          Size in
    Input_type_code          Format                       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

    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 number can be floating-point data in F_
    Floating, D_Floating, G_Floating, H_Floating, IEEE_S_Floating,
    IEEE_T_Floating, IEEE_X_Floating, Big_Endian_IEEE_S_Floating,
    Big_Endian_IEEE_T_Floating, Big_Endian_IEEE_X_Floating, IBM_Long_
    Floating, IBM_Short_Floating, or CRAY_Floating_Single format. The
    value of the output_type_code argument determines the size and
    format of the converted floating-point number.

 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:

                                                          Size in
    Output_type_code         Format                       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

    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. Provide
    a zero (0) value to the options argument to select default
    behavior or choose one or more options (status condition option,
    rounding options, "FORCE" options, CRAY and IBM options) from
    the following tables. Specify only the options that apply to your
    conversion. A conflicting or incompatible options argument is
    reported as an error (CVT$M_INVALID_OPTION).

    Applicable
    ConversioOption                Description

                              Status Condition Option

    All      CVT$M_REPORT_ALL      Report all applicable status
                                   conditions as the default. The
                                   reporting of recoverable status
                                   conditions is disabled by default
                                   when this option is not used.

                                 Rounding Options

    All      CVT$M_ROUND_TO_       The default rounding option for
             NEAREST               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.
    All      CVT$M_BIASED_         The default rounding option for
             ROUNDING              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.
    All      CVT$M_ROUND_TO_ZERO   Round the output value toward zero
                                   (truncate).
    All      CVT$M_ROUND_TO_POS    Round the output value toward
                                   positive infinity.
    All      CVT$M_ROUND_TO_NEG    Round the output value toward
                                   negative infinity.

                                  "FORCE" Options

    All      CVT$M_FORCE_ALL_      Apply all applicable "FORCE"
             SPECIAL_VALUES        options for the current
                                   conversion.
    IEEE     CVT$M_FORCE_DENORM_   Force a denormalized IEEE output
             TO_ZERO               value to zero.
    IEEE     CVT$M_FORCE_INF_TO_   Force a positive IEEE infinite
             MAX_FLOAT             output value to +max_float and
                                   force a negative IEEE infinite
                                   output value to -max_float.
    IEEE     CVT$M_FORCE_          Force an invalid IEEE NaN (not a
    or VAX   INVALID_TO_ZERO       number) output value or a VAX ROP
                                   (reserved operand) output value to
                                   zero.

                          CRAY Format Conversion Options

    CRAY     CVT$M_ALLOW_OVRFLW_   Allow an input/output exponent
             RANGE_VALUES          value > 60000 (8).
    CRAY     CVT$M_ALLOW_UDRFLW_   Allow an input/output exponent
             RANGE_VALUES          value < 20000 (8).

                       IBM Format Conversion Option

    IBM      CVT$M_ALLOW_          Allow unnormalized input
             UNNORMALIZED_VALUES   arguments. Allow an unnormalized
                                   output value for a small value
                                   that would normalize to zero.

    The maximum representable floating-point values (max_float) for
    the IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, Big_
    Endian_IEEE_S_Floating, Big_Endian_IEEE_T_Floating, and Big_
    Endian_IEEE_X_Floating formats are:

    Data
    Type Value for: max_float

    S    Decimal: 3.402823e38
    T    Decimal: 1.797693134862316e308
    X    Decimal: 1.189731495357231765085759326628007016196477e4932

    Declarations for the options argument are in the $CVTDEF module
    found in the system symbol libraries.

2  –  LIB$

2.1  –  LIB$ADAWI

    The Add Aligned Word with Interlock routine allows the user to
    perform an interlocked add operation using an aligned word.

    Format

      LIB$ADAWI  add ,sum ,sign

2.1.1  –  Returns

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

2.1.2  –  Arguments

 add

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by reference

    The addend operand to be added to the value of sum. The add
    argument is the address of a signed word that contains the addend
    operand.

 sum

    OpenVMS usage:word_signed
    type:         word integer (signed)
    access:       modify
    mechanism:    by reference

    The word to which add is added. The sum argument is the address
    of a signed word integer containing this value. The add operand
    is added to the sum operand, and the value of the sum argument is
    replaced by the result of this addition. The sum argument must be
    word-aligned; in other words, its address must be a multiple of
    2.

 sign

    OpenVMS usage:word_signed
    type:         word integer (signed)
    access:       write only
    mechanism:    by reference

    Sign of the sum argument. The sign argument is the address of
    a signed word integer that is assigned the value -1, 0, or 1,
    depending on whether the new value of sum is negative, 0, or
    positive.

2.2  –  LIB$ADDX

    The Add Two Multiple-Precision Binary Numbers routine adds two
    signed two's complement integers of arbitrary length.

    Format

      LIB$ADDX  addend-array ,augend-array ,resultant-array

                [,array-length]

2.2.1  –  Returns

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

2.2.2  –  Arguments

 addend-array

    OpenVMS usage:vector_longword_signed
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    First multiple-precision, signed two's complement integer that
    LIB$ADDX adds to the second two's complement integer. The addend-
    array argument is the address of the array containing the two's
    complement number to be added.

 augend-array

    OpenVMS usage:vector_longword_signed
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Second multiple-precision, signed two's complement integer that
    LIB$ADDX adds to the first two's complement integer. The augend-
    array argument is the address of the array containing the two's
    complement number.

 resultant-array

    OpenVMS usage:vector_longword_signed
    type:         unspecified
    access:       write only
    mechanism:    by reference, array reference

    Multiple-precision, signed two's complement integer result of
    the addition. The resultant-array argument is the address of the
    array into which LIB$ADDX writes the result of the addition.

 array-length

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

    Length in longwords of the arrays to be operated on; each array
    is of length array-length. The array-length argument is the
    address of a signed longword integer containing the length. The
    array-length argument must not be negative. This is an optional
    argument. If omitted, the default is 2.

2.3  –  LIB$ADD_TIMES

    The Add Two Quadword Times routine adds two internal format
    times.

    Format

      LIB$ADD_TIMES  time1 ,time2 ,resultant-time

2.3.1  –  Returns

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

2.3.2  –  Arguments

 time1

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    First time that LIB$ADD_TIMES adds to the second time. The time1
    argument is the address of an unsigned quadword containing the
    first time to be added. The time1 argument may be either a delta
    time or an absolute time; however, at least one of the arguments,
    time1 or time2, must be a delta time.

 time2

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Second time that LIB$ADD_TIMES adds to the first time. The time2
    argument is the address of an unsigned quadword containing the
    second time to be added. The time2 argument may be either a delta
    time or an absolute time; however, at least one of the arguments,
    time1 or time2, must be a delta time.

 resultant-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    The result of adding time1 and time2. The resultant-time argument
    is the address of an unsigned quadword containing the result. If
    both time1 and time2 are delta times, then resultant-time is a
    delta time. Otherwise, resultant-time is an absolute time.

2.4  –  LIB$ANALYZE_SDESC

    The Analyze String Descriptors routine extracts the length and
    the address at which the data starts for a variety of 32-bit
    string descriptor classes.

    Format

      LIB$ANALYZE_SDESC  input-descriptor ,data-length ,data-address

2.4.1  –  Corresponding JSB Entry Point

      LIB$ANALYZE_SDESC_R2

2.4.2  –  Returns

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

2.4.3  –  Arguments

 input-descriptor

    OpenVMS usage:descriptor
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Input descriptor from which LIB$ANALYZE_SDESC extracts the length
    of the data and the address at which the data starts. The input-
    descriptor argument is the address of a descriptor pointing to
    the input data.

 data-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the data; LIB$ANALYZE_SDESC extracts this length
    value from the input descriptor. The data-length argument is the
    address of an unsigned word integer into which LIB$ANALYZE_SDESC
    writes the length.

 data-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Starting address of the data; LIB$ANALYZE_SDESC extracts this
    address from the input descriptor. The data-address argument is
    the address of an unsigned longword into which LIB$ANALYZE_SDESC
    writes the starting address of the data.

2.5  –  LIB$ANALYZE_SDESC_64

    (Alpha and I64 only.) The Analyze String Descriptor routine
    extracts the length and the address at which the data starts
    for a variety of 32-bit and 64-bit string descriptor classes.

    Format

      LIB$ANALYZE_SDESC_64  input-descriptor ,data-length

                            ,data-address [,descriptor-type]

2.5.1  –  Corresponding JSB Entry Point

      LIB$ANALYZE_SDESC_R2   Refer to the LIB$ANALYZE_SDESC routine
                            for information about the JSB entry
                            point, LIB$ANALYZE_SDESC_R2. This JSB
                            entry point returns 64-bit results on
                            Alpha and I64 systems.

2.5.2  –  Returns

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

2.5.3  –  Arguments

 input-descriptor

    OpenVMS usage:descriptor
    type:         longword (unsigned) or quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Input descriptor from which LIB$ANALYZE_SDESC_64 extracts the
    length of the data and the address at which the data starts. The
    input-descriptor argument is the address of a descriptor pointing
    to the input data. The input descriptor can be a longword
    (unsigned) or a quadword (unsigned).

 data-length

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the data; LIB$ANALYZE_SDESC_64 extracts this length
    value from the input descriptor. The data-length argument is the
    address of an unsigned quadword integer into which LIB$ANALYZE_
    SDESC_64 writes the length.

 data-address

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Starting address of the data; LIB$ANALYZE_SDESC_64 extracts this
    address from the input descriptor. The data-address argument is
    the address of an unsigned quadword into which LIB$ANALYZE_SDESC_
    64 writes the starting address of the data.

 descriptor-type

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

    Flag value indicating the type of input descriptor. The
    descriptor-type argument contains the address of an unsigned
    longword integer to which LIB$ANALYZE_SDESC_64 writes a 0 for a
    32-bit input descriptor or a 1 for a 64-bit descriptor.

    This argument is optional.

2.6  –  LIB$ASN_WTH_MBX

    The Assign Channel with Mailbox routine assigns a channel to a
    specified device and associates a mailbox with the device. It
    returns both the device channel and the mailbox channel.

    Format

      LIB$ASN_WTH_MBX  device-name [,maximum-message-size]

                       [,buffer-quota] ,device-channel

                       ,mailbox-channel

2.6.1  –  Returns

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

2.6.2  –  Arguments

 device-name

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

    Device name that LIB$ASN_WTH_MBX passes to the $ASSIGN service.
    The device-name argument is the address of a descriptor pointing
    to the device name.

 maximum-message-size

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

    Maximum message size that can be sent to the mailbox; LIB$ASN_
    WTH_MBX passes this argument to the $CREMBX service. The maximum-
    message-size argument is the address of a signed longword integer
    containing this maximum message size.

 buffer-quota

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

    Number of system dynamic memory bytes that can be used to buffer
    messages sent to the mailbox; LIB$ASN_WTH_MBX passes this
    argument to the $CREMBX service. The buffer-quota argument is
    the address of a signed longword integer containing this buffer
    quota.

 device-channel

    OpenVMS usage:word_unsigned
    type:         word integer (unsigned)
    access:       write only
    mechanism:    by reference

    Device channel that LIB$ASN_WTH_MBX receives from the $ASSIGN
    service. The device-channel argument is the address of an
    unsigned word integer into which $ASSIGN writes the device
    channel.

 mailbox-channel

    OpenVMS usage:channel
    type:         word integer (unsigned)
    access:       write only
    mechanism:    by reference

    Mailbox channel that LIB$ASN_WTH_MBX receives from the $CREMBX
    service. The mailbox-channel argument is the address of an
    unsigned word integer into which $CREMBX writes the mailbox
    channel.

2.7  –  LIB$AST_IN_PROG

    The AST in Progress routine indicates whether an AST is currently
    in progress.

    Format

      LIB$AST_IN_PROG

2.7.1  –  Returns

    OpenVMS usage:boolean
    type:         boolean
    access:       write only
    mechanism:    by value

    Truth value that indicates whether an AST is currently in
    progress (value = 1) or not (value = 0).

2.7.2  –  Arguments

    None.

2.8  –  LIB$ATTACH

    The Attach Terminal to Process routine requests the calling
    process's command language interpreter (CLI) to detach the
    terminal of the calling process and to reattach it to a different
    process.

    Format

      LIB$ATTACH  process-id

2.8.1  –  Returns

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

2.8.2  –  Argument

 process-id

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

    Identification of the process to which LIB$ATTACH requests the
    calling process to attach its terminal. The process-id argument
    is the address of an unsigned longword integer containing the
    process identification. The specified process must be currently
    detached (by means of a SPAWN or ATTACH command or by a call to
    LIB$SPAWN or LIB$ATTACH) and must be part of the caller's job.

2.9  –  LIB$BBCCI

    The Test and Clear Bit with Interlock routine tests and clears
    a selected bit under memory interlock. LIB$BBCCI makes the VAX
    BBCCI instruction available as a callable routine.

    Format

      LIB$BBCCI  position ,bit-zero-address

2.9.1  –  Returns

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

    State of the bit before it was cleared by LIB$BBCCI: 1 if the bit
    was previously set, and 0 if the bit was previously clear.

2.9.2  –  Arguments

 position

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

    Bit position, relative to bit-zero-address, of the bit that
    LIB$BBCCI tests and clears. The position argument is the address
    of a signed longword integer containing the bit position. A
    position of zero denotes the low-order bit of the byte base. The
    bit position is equal to the offset of the bit chosen from the
    base position. This offset may span the entire range of a signed
    longword integer; negative offsets access bits in lower addressed
    bytes.

 bit-zero-address

    OpenVMS usage:unspecified
    type:         address
    access:       read only
    mechanism:    by value

    Address of the byte containing bit 0 of the field that LIB$BBCCI
    references. The bit-zero-address argument is the location of
    the base position. The bit that LIB$BBCCI tests and clears is
    position bits offset from the low bit of bit-zero-address.

2.10  –  LIB$BBSSI

    The Test and Set Bit with Interlock routine tests and sets a
    selected bit under memory interlock. LIB$BBSSI makes the VAX
    BBSSI instruction available as a callable routine.

    Format

      LIB$BBSSI  position ,bit-zero-address

2.10.1  –  Returns

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

    The state of the bit before it was set by LIB$BBSSI: 1 if it was
    previously set, and 0 if it was previously clear.

2.10.2  –  Arguments

 position

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

    Bit position, relative to bit-zero-address, of the bit that
    LIB$BBSSI tests and sets. The position argument is the address
    of a signed longword integer containing the bit position. A
    position of zero denotes the low-order bit of the byte base. The
    bit position is equal to the offset of the bit chosen from the
    base position. This offset may span the entire range of a signed
    longword integer; negative offsets access bits in lower addressed
    bytes.

 bit-zero-address

    OpenVMS usage:unspecified
    type:         address
    access:       read only
    mechanism:    by value

    Address of the byte containing bit 0 of the field that LIB$BBSSI
    references. The bit-zero-address argument is the location of the
    base position. The bit that LIB$BBSSI tests and sets is position
    bits offset from the low bit of bit-zero-address.

2.11  –  LIB$BUILD_NODESPEC

    The Build a Node-Name Specification routine builds a node-name
    specification from the primary node name. The output node-name
    specification can be used for other node-name parsing operations.

    Format

      LIB$BUILD_NODESPEC  primary-nodename, nodespec [,acs]

                          [,secondary-nodename] [,nodespec-length]

2.11.1  –  Returns

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

2.11.2  –  Arguments

 primary-nodename

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

    Primary node name. The primary-nodename argument contains the
    address of a descriptor pointing to this node-name string. The
    primary node name should not contain unnecessary quotation marks
    (that is, quotation marks (" ") that are not part of a simple
    name within the node name).

    The error LIB$_INVARG is returned if primary-nodename points to
    a null string. The error LIB$_INVSTRDES is returned if primary-
    nodename is an invalid descriptor.

 nodespec

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

    Node-name specification. The nodespec argument contains the
    address of a descriptor pointing to this output node-name
    specification string. LIB$BUILD_NODESPEC writes the output node-
    name specification into the buffer pointed to by the nodespec
    descriptor.

    The error LIB$_INVSTRDES is returned if nodespec is an invalid
    descriptor.

    The length field of the nodespec descriptor is not updated unless
    nodespec is a dynamic descriptor with a length less than the
    resultant node-name specification. Refer to the OpenVMS RTL
    String Manipulation (STR$) Manual for dynamic string descriptor
    usage.

    The nodespec argument contains an unusable result when LIB$BUILD_
    NODESPEC returns in error.

 acs

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

    Access control string. The acs argument contains the address of
    a descriptor pointing to this access control string. The access
    control string must be a quoted string.

    The error LIB$_INVSTRDES is returned if acs is an invalid
    descriptor.

 secondary-nodename

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

    Secondary node name. The secondary-nodename argument contains
    the address of a descriptor pointing to this secondary node-name
    string.

    The error LIB$_INVSTRDES is returned if secondary-nodename is an
    invalid descriptor.

 nodespec-length

    OpenVMS usage:unsigned_word
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the output node-name specification. The nodespec-length
    argument is the address of an unsigned word that contains this
    length in bytes.

    The nodespec-length argument contains an unusable result when
    LIB$BUILD_NODESPEC returns in error.

2.12  –  LIB$CALLG

    The Call Routine with General Argument List routine calls a
    routine with an argument list specified as an array of longwords,
    the first of which is a count of the remaining longwords.
    LIB$CALLG is a callable version of the VAX CALLG instruction.

    Format

      LIB$CALLG  argument-list ,user-procedure

2.12.1  –  Returns

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

    Return value, if any, of the called routine, unchanged by
    LIB$CALLG.

2.12.2  –  Arguments

 argument-list

    OpenVMS usage:arg_list
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Argument list to be passed to user-procedure. The argument-
    list argument is the address of an array of longwords that is
    the argument list. The first longword contains the count of the
    remaining longwords, to a maximum of 255.

 user-procedure

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

    Routine that LIB$CALLG calls with the specified argument list.

2.13  –  LIB$CALLG_64

    (Alpha and I64 only.) The Call Routine with General Argument
    List routine calls a routine with an argument list specified
    as an array of quadwords, the first of which is a count of the
    remaining quadwords.

    Format

      LIB$CALLG_64  argument-list ,user-procedure

2.13.1  –  Returns

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by value

    Return value, if any, of the called routine, unchanged by
    LIB$CALLG_64.

2.13.2  –  Arguments

 argument-list

    OpenVMS usage:arg_list
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Argument list to be passed to user-procedure. The argument-
    list argument is the address of an array of quadwords that is
    the argument list. The first quadword contains the count of the
    remaining quadwords, to a maximum of 255.

 user-procedure

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

    Routine that LIB$CALLG_64 calls with the specified argument list.

2.14  –  LIB$CHAR

    The Transform Byte to First Character of String routine
    transforms a single 8-bit ASCII character to an ASCII string
    consisting of a single character followed by trailing spaces, if
    needed, to fill out the string. The range of the input byte is 0
    through 255.

    Format

      LIB$CHAR  one-character-string ,ascii-code

2.14.1  –  Returns

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

2.14.2  –  Arguments

 one-character-string

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

    ASCII character string consisting of a single character followed
    by trailing spaces, if needed, that LIB$CHAR creates when it
    transforms the ASCII character code. The one-character-string
    argument is the address of a descriptor pointing to the character
    string that LIB$CHAR writes.

 ascii-code

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Single 8-bit ASCII character code that LIB$CHAR transforms to
    an ASCII string. The ascii-code argument is the address of an
    unsigned byte containing the ASCII character code.

2.15  –  LIB$COMPARE_NODENAME

    The Compare Two Node Names routine compares two node names to see
    if they resolve to the same full name.

    Format

      LIB$COMPARE_NODENAME  nodename1 ,nodename2 ,comparison-result

2.15.1  –  Returns

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

2.15.2  –  Arguments

 nodename1

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

    First node name to be compared. The nodename1 argument contains
    the address of a descriptor pointing to this node-name string.

    The error LIB$_INVARG is returned if nodename1 contains an
    invalid node name, points to a null string, or contains more
    than 1024 characters. The error LIB$_INVSTRDES is returned if
    nodename1 is an invalid descriptor.

 nodename2

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

    Second node name to be compared. The nodename2 argument contains
    the address of a descriptor pointing to this node-name string.

    The error LIB$_INVARG is returned if nodename2 contains an
    invalid node name, points to a null string, or contains more
    than 1024 characters. The error LIB$_INVSTRDES is returned if
    nodename2 is an invalid descriptor.

 comparison-result

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

    Result of the comparison. The comparison-result argument is the
    address of an unsigned longword that contains the comparison
    result. If the two node names are equal, 0 is returned. If they
    are not equal, 1 is returned.

    Comparison-result contains an unusable result when LIB$COMPARE_
    NODENAME returns in error.

2.16  –  LIB$COMPRESS_NODENAME

    The Compress a Node Name to Its Short Form Equivalence routine
    compresses a node name to an unambiguous short form usable within
    the naming environment where the compression is performed.

    Format

      LIB$COMPRESS_NODENAME  nodename ,compressed-nodename

                             [,resultant-length]

2.16.1  –  Returns

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

2.16.2  –  Arguments

 nodename

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

    Node name to be compressed. The nodename argument contains the
    address of a descriptor pointing to this node-name string.

    The error LIB$_INVARG is returned if nodename contains an invalid
    node name, points to a null string, or contains more than 1024
    characters. The error LIB$_INVSTRDES is returned if the nodename
    descriptor is invalid.

 compressed-nodename

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

    Compressed node name. The compressed-nodename argument contains
    the address of a descriptor pointing to the compressed node-name
    string. LIB$COMPRESS_NODENAME writes the compressed node name
    into the buffer pointed to by compressed-nodename.

    The error LIB$_INVSTRDES is returned if compressed-nodename is an
    invalid descriptor.

    The length field of the compressed-nodename descriptor is not
    updated unless compressed-nodename is a dynamic descriptor with a
    length less than the resulting compressed node name. Refer to the
    OpenVMS RTL String Manipulation (STR$) Manual for dynamic string
    descriptor usage.

    The compressed-nodename argument contains an unusable result when
    LIB$COMPRESS_NODENAME returns in error.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the compressed node name. The resultant-length argument
    is the address of an unsigned word that contains this length in
    bytes.

    The resultant-length argument contains an unusable result when
    LIB$COMPRESS_NODENAME returns in error.

2.17  –  LIB$CONVERT_DATE_STRING

    The Convert Date String to Quadword routine converts an absolute
    date string into an OpenVMS internal format date-time quadword.
    That is, given an input date/time string of a specified format,
    LIB$CONVERT_DATE_STRING converts this string to an OpenVMS
    internal format time.

    Format

      LIB$CONVERT_DATE_STRING  date-string ,date-time

                               [,user-context] [,flags] [,defaults]

                               [,defaulted-fields]

2.17.1  –  Returns

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

2.17.2  –  Arguments

 date-string

    OpenVMS usage:time_name
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor

    Date string that specifies the absolute time to be converted
    to an internal system time. The date-string argument is the
    address of a descriptor pointing to this date string. This string
    must have a format corresponding to the currently defined input
    format, or it must be one of the relative day strings YESTERDAY,
    TODAY, or TOMORROW, or their equivalents in the currently
    selected language.

 date-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the converted time. The date-time argument is the
    address of an unsigned quadword that contains this OpenVMS
    internal format converted time.

 user-context

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

    Context variable that receives the translation context
    from a call to LIB$INIT_DATE_TIME_CONTEXT and then
    retains the translation context over multiple calls to
    LIB$CONVERT_DATE_STRING. The user-context argument is the address
    of an unsigned longword that contains this context. The user
    program should not write directly to this variable once it is
    initialized.

    The user-context parameter is optional. However, if a context
    cell is not passed, the routine LIB$CONVERT_DATE_STRING may
    abort if two threads of execution attempt to manipulate the
    context area concurrently. Therefore, when calling this routine
    in situations where reentrancy might occur, such as from AST
    level, VSI recommends that users specify a different context cell
    for each calling thread.

 flags

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

    Specifies which date or time fields of the date-string argument
    might be omitted so that default values are applied. The flags
    argument is the address of a longword bit mask that contains
    these flags. A set bit indicates that the field may be omitted.
    The bit definitions for the mask correspond to the fields in a
    $NUMTIM "timbuf" structure as follows:

    Field           Bit Number  Mask

    Year            0            1
    Month           1            2
    Day of month    2            4
    Hours           3            8
    Minutes         4           16
    Seconds         5           32
    Fractional      6           64
    seconds

    Bits 7 through 31 must be zero and are Reserved for use by VSI. If
    this parameter is omitted, a default value of 120 (78H) is used,
    indicating that the time fields may be defaulted but the date
    fields may not.

 defaults

    OpenVMS usage:vector_word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference, array reference

    Supplies the defaults to be used for omitted fields. The defaults
    argument is the address of an array of unsigned words containing
    these default values. This array corresponds to a 7-word $NUMTIM
    "timbuf" structure. If the defaults argument is omitted, the
    following defaults are applied:

    o  For the date group, the default is the current date.

    o  For the time group, the default is 00:00:00.00.

 defaulted-fields

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

    Indicates which date or time fields have been defaulted. The
    defaulted-fields argument is the address of a longword bit mask
    that specifies these fields. The bit definitions are identical to
    those of the flags bit mask. A set bit indicates that the field
    was defaulted. Bits 7 through 31, which are reserved for use by
    VSI, are zeroed.

2.18  –  LIB$CRC

    The Calculate a Cyclic Redundancy Check routine calculates the
    cyclic redundancy check (CRC) for a data stream.

    Format

      LIB$CRC  crc-table ,initial-crc ,stream

2.18.1  –  Returns

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

    The computed cyclic redundancy check.

2.18.2  –  Arguments

 crc-table

    OpenVMS usage:vector_longword_signed
    type:         longword integer (signed)
    access:       read only
    mechanism:    by reference, array reference

    The 16-longword cyclic redundancy check table created by a call
    to LIB$CRC_TABLE. The crc-table argument is the address of a
    signed longword integer containing this table. Because this table
    is created by LIB$CRC_TABLE and then used as input in LIB$CRC,
    your program must call LIB$CRC_TABLE before it calls LIB$CRC.

 initial-crc

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

    Initial cyclic redundancy check. The initial-crc argument is
    the address of a signed longword integer containing the initial
    cyclic redundancy check.

 stream

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

    Data stream for which LIB$CRC is calculating the CRC. The stream
    argument is the address of a descriptor pointing to the data
    stream.

2.19  –  LIB$CRC_TABLE

    The Construct a Cyclic Redundancy Check Table routine constructs
    a 16-longword table that uses a cyclic redundancy check
    polynomial specification as a bit mask.

    Format

      LIB$CRC_TABLE  polynomial-coefficient ,crc-table

2.19.1  –  Returns

    None.

2.19.2  –  Arguments

 polynomial-coefficient

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    A bit mask indicating which polynomial coefficients are to be
    generated by LIB$CRC_TABLE. The polynomial-coefficient argument
    is the address of an unsigned longword integer containing this
    bit mask.

 crc-table

    OpenVMS usage:vector_longword_signed
    type:         longword integer (signed)
    access:       write only
    mechanism:    by reference, array reference
    The 16-longword table that LIB$CRC_TABLE produces. The crc-table
    argument is the address of a signed longword integer containing
    the table.

2.20  –  LIB$CREATE_DIR

    The Create a Directory routine creates a directory or
    subdirectory.

    Format

      LIB$CREATE_DIR  device-directory-spec [,owner-UIC]

                      [,protection-enable] [,protection-value]

                      [,maximum-versions] [,relative-volume-number]

                      [,initial-allocation]

2.20.1  –  Returns

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

2.20.2  –  Arguments

 device-directory-spec

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

    Directory specification of the directory or subdirectory that
    LIB$CREATE_DIR will create. The device-directory-spec argument
    is the address of a descriptor pointing to this directory
    specification.

    The format of the device-directory-spec string conforms
    to standard OpenVMS Record Management Services (RMS)
    format. This specification must contain a directory or
    subdirectory specification. It may contain a disk specification.
    SMD$:[THIS.IS.IT] is an example of a standard RMS file
    specification, where SMD$ is the disk specification and
    [THIS.IS.IT] is the subdirectory specification.

    This specification cannot contain a node name, file name, file
    type, file version, or wildcard characters. The maximum size
    of this string is 255 characters on VAX, and 4095 characters on
    Alpha.

 owner-UIC

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

    User identification code (UIC) identifying the owner of the
    created directory or subdirectory. The owner-UIC argument is the
    address of an unsigned longword that contains the UIC. If owner-
    UIC is zero, the owner UIC is that of the parent directory. The
    specified value for owner-UIC is interpreted as a 32-bit octal
    number, with two 16-bit fields:

       bits 00-15 - Member number
       bits 16-31 - Group number

    This is an optional argument. The default is the UIC of the
    current process except when the directory is in UIC format. For
    a directory in UIC format, for example [123,321], the UIC of the
    created directory is used.

 protection-enable

    OpenVMS usage:mask_word
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Mask specifying the bits of protection-value to be set. The
    protection-enable argument is the address of an unsigned word
    containing this protection mask.

    The following diagram shows the structure of a protection mask.
    Access is allowed for bits set to 0.

           World           Group          Owner           System
    +_______________+_______________+_______________+_______________+
    | D | W | E | R | D | W | E | R | D | W | E | R | D | W | E | R |
    _________________________________________________________________
     15                                                           0

    Bits set in the protection-enable mask cause corresponding bits
    of protection-value to be set. Bits not set in the protection-
    enable mask cause corresponding bits of protection-value to take
    the value of the corresponding bit in the parent directory's
    file protection. Bits in the parent directory's file protection
    that indicate delete access do not cause corresponding bits of
    protection-value to be set, however.

    Following is an example of how the protection-value protection
    mask is defined:

                     Hexadecimal
    Mask Name        Number      Value

    Protection       %XDBFF      S:None, O:None, G:E, W:W
    enable
    Parent           %X13FF      S:RWED, O:RWED, G:RW, W:R
    directory
    Protection       %X37FF      S:RWE, O:RWE, G:RWE, W:RW
    value

    The protection-enable argument is optional. It should be
    used only when you want to change protection values from the
    parent directory's default file protection. The default for
    protection-enable is a mask of all zero bits, which results in
    the propagation of the parent directory's file protection. If
    the protection-enable mask contains zeros, protection-value is
    ignored.

 protection-value

    OpenVMS usage:file_protection
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    System/Owner/Group/World protection value of the directory you
    are creating. The protection-value argument is the address of an
    unsigned word that contains this protection mask.

    The bits of protection-value are set or cleared in the method
    described in the definition of protection-enable above.

    The protection-value argument is optional. The default is a word
    of all zero bits, which specifies full access for all access
    categories. Typically, protection-value is not omitted unless
    protection-enable is also omitted. If protection-enable is
    omitted, protection-value is ignored.

 maximum-versions

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Maximum number of versions allowed for files created in the newly
    created directories. The maximum-versions argument is the address
    of an unsigned word containing the value of the maximum number of
    versions.

    The maximum-versions argument is optional. The default is the
    parent directory's default version limit. If maximum-versions is
    zero, the maximum number of versions is not limited.

 relative-volume-number

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Relative volume number within a volume set on which the directory
    or subdirectory is created. The relative-volume-number argument
    is the address of an unsigned word containing the relative volume
    number. The relative-volume-number argument is optional. The
    default is arbitrary placement within the volume set.

 initial-allocation

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

    Initial number of blocks to be allocated to the directory. This
    argument is useful for creating large directories, for example
    MAIL.DIR;1. It can improve performance by avoiding the need for
    later dynamic expansion of the directory.

    The initial-allocation argument applies only to Files-11 Level 2
    volumes; it is ignored for other volumes.

    This argument is the address of an unsigned longword that
    contains the initial number of blocks to be allocated to the
    directory.

    The initial-allocation argument is optional. The default
    allocation is 1 block.

2.21  –  LIB$CREATE_USER_VM_ZONE

    The Create User-Defined Storage Zone routine creates a new user-
    defined storage zone in the 32-bit virtual address space.

    Format

      LIB$CREATE_USER_VM_ZONE  zone-id [,user-argument]

                               [,user-allocation-procedure]

                               [,user-deallocation-procedure]

                               [,user-reset-procedure]

                               [,user-delete-procedure] [,zone-name]

2.21.1  –  Returns

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

2.21.2  –  Arguments

 zone-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Zone identifier. The zone-id argument is the address of a
    longword that receives the identifier of the newly created zone.

 user-argument

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

    User argument. The user-argument argument is the address of an
    unsigned longword containing the user argument. LIB$CREATE_USER_
    VM_ZONE copies the value of user-argument and supplies the value
    to all user procedures invoked.

 user-allocation-procedure

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

    User allocation routine.

 user-deallocation-procedure

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

    User deallocation routine.

 user-reset-procedure

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

    User routine invoked each time LIB$RESET_VM_ZONE is called for
    the zone.

 user-delete-procedure

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

    User routine invoked when LIB$DELETE_VM_ZONE is called for the
    zone.

 zone-name

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

    Name to be associated with the zone being created. The optional
    zone-name argument is the address of a descriptor pointing to the
    zone name. If zone-name is not specified, the zone will not have
    an associated name.

2.22  –  LIB$CREATE_USER_VM_ZONE_64

    (Alpha and only.) The Create User-Defined Storage Zone routine
    creates a new user-defined storage zone in the 64-bit virtual
    address space.

    Format

      LIB$CREATE_USER_VM_ZONE_64  zone-id [,user-argument]

                                  [,user-allocation-procedure]

                                  [,user-deallocation-procedure]

                                  [,user-reset-procedure]

                                  [,user-delete-procedure]

                                  [,zone-name]

2.22.1  –  Returns

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

2.22.2  –  Arguments

 zone-id

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Zone identifier. The zone-id argument is the address of a
    quadword that receives the identifier of the newly created zone.

 user-argument

    OpenVMS usage:user_arg
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    User argument. The user-argument argument is the address of an
    unsigned quadword containing the user argument. LIB$CREATE_USER_
    VM_ZONE_64 copies the value of user-argument and supplies the
    value to all user procedures invoked.

 user-allocation-procedure

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

    User allocation routine.

 user-deallocation-procedure

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

    User deallocation routine.

 user-reset-procedure

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

    User routine invoked each time LIB$RESET_VM_ZONE_64 is called for
    the zone.

 user-delete-procedure

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

    User routine invoked when LIB$DELETE_VM_ZONE_64 is called for the
    zone.

 zone-name

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

    Name to be associated with the zone being created. The optional
    zone-name argument is the address of a descriptor pointing to the
    zone name. If zone-name is not specified, the zone will not have
    an associated name.

2.23  –  LIB$CREATE_VM_ZONE

    The Create a New Zone routine creates a new storage zone in the
    32-bit virtual address space, according to specified arguments.

    Format

      LIB$CREATE_VM_ZONE  zone-id [,algorithm] [,algorithm-argument]

                          [,flags] [,extend-size] [,initial-size]

                          [,block-size] [,alignment] [,page-limit]

                          [,smallest-block-size] [,zone-name]

                          [,get-page] [,free-page]

2.23.1  –  Returns

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

2.23.2  –  Arguments

 zone-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Zone identifier. The zone-id argument is the address of a
    longword that is set to the zone identifier of the newly created
    zone.

 algorithm

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

    Algorithm. The algorithm argument is the address of a longword
    integer that contains a value representing one of the LIB$VM
    algorithms. Use one of the predefined symbols to specify this
    value.

    Symbol                  Value  Algorithm

    LIB$K_VM_FIRST_FIT      1      First fit
    LIB$K_VM_QUICK_FIT      2      Quick fit, lookaside list
    LIB$K_VM_FREQ_SIZES     3      Frequent sizes, lookaside list
    LIB$K_VM_FIXED          4      Fixed-size blocks

    If algorithm is not specified, a default of 1 (first fit) is
    used.

 algorithm-argument

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

    Algorithm argument. The algorithm-argument argument is the
    address of a longword integer that contains a value specific
    to the particular allocation algorithm as shown in the following
    table.

    Algorithm      Value

    First fit      Not used, may be omitted.
    Quick fit      The number of lookaside lists used. The number of
                   lists must be between 1 and 128.
    Frequent       The number of lookaside lists used. The number of
    sizes          lists must be between 1 and 16.
    Fixed size     The fixed request size (in bytes) for each get
    blocks         or free request. The request size must be greater
                   than 0.

    The algorithm-argument argument must be specified if you are
    using the quick-fit, frequent-sizes or fixed-size-blocks
    algorithms. However, this argument is optional, but ignored,
    if you are using the first-fit algorithm.

 flags

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

    Flags. The flags argument is the address of a longword integer
    that contains flag bits that control various options, as follows:

    Bit    Value                 Description

    0      LIB$M_VM_BOUNDARY_    Boundary tags for faster freeing.
           TAGS
                                 Adds a minimum of 8 bytes to each
                                 block.
    1      LIB$M_VM_GET_FILL0    LIB$GET_VM; fill with bytes of 0.
    2      LIB$M_VM_GET_FILL1    LIB$GET_VM; fill with bytes of FF
                                 (hexadecimal).
    3      LIB$M_VM_FREE_FILL0   LIB$FREE_VM; fill with bytes of 0.
    4      LIB$M_VM_FREE_FILL1   LIB$FREE_VM; fill with bytes of FF
                                 (hexadecimal).
    5      LIB$M_VM_EXTEND_      Adds extents to existing areas if
           AREA                  possible.
    6      LIB$M_VM_NO_EXTEND    Prevents zone from being extended
                                 beyond its initial size. If you
                                 specify this flag, you must also
                                 specify an initial-size. The extend-
                                 size argument is not used.
    7      LIB$M_VM_TAIL_LARGE   Adds areas larger than extend-size
                                 areas to the end of the area list.
                                 Allocations that are larger than
                                 extend-size can result in new areas.
                                 These areas are added to the end of
                                 the area list. (This provides better
                                 memory reuse when allocating small
                                 and very large blocks from the same
                                 zone.)

    Bits 8 through 31 are reserved and must be 0.

    This is an optional argument. If flags is omitted, the default of
    0 (no fill and no boundary tags) is used.

 extend-size

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

    Zone extend size. The extend-size argument is the address of a
    longword integer that contains the number of (512-byte) pages on
    VAX systems or pagelets on Alpha and I64 systems to be added to
    the zone each time it is extended.

    The value of extend-size must be greater than or equal to 1.

    This is an optional argument. If extend-size is not specified, a
    default of 16 pages on VAX systems or pagelets on Alpha and I64
    systems is used.

                                   NOTE

       The extend-size argument does not limit the number of blocks
       that can be allocated from the zone. The actual extension
       size is the greater of extend-size and the number of pages
       on VAX systems or pagelets on Alpha and I64 systems needed
       to satisfy the LIB$GET_VM call that caused the extension.

 initial-size

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

    Initial size for the zone. The initial-size argument is the
    address of a longword integer that contains the number of (512-
    byte) pages on VAX systems or pagelets on Alpha and I64 systems
    to be allocated for the zone as the zone is created.

    This is an optional argument. If you specify a value for initial-
    size, the value must be greater than or equal to 0; otherwise,
    LIB$_INVARG is returned. If initial-size is not specified or is
    specified as 0, no pages on VAX systems or pagelets on Alpha and
    I64 systems are allocated when the zone is created. The first
    call to LIB$GET_VM for the zone allocates extend-size pages on
    VAX systems or pagelets on Alpha and I64 systems.

 block-size

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

    Block size of the zone. The block-size argument is the address of
    a longword integer specifying the allocation quantum (in bytes)
    for the zone. All blocks allocated are rounded up to a multiple
    of block-size.

    The value of block-size must be a power of 2 between 8 and 512.
    This is an optional argument. If block-size is not specified, a
    default of 8 is used.

 alignment

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

    Block alignment. The alignment argument is the address of a
    longword integer that specifies the required address alignment
    (in bytes) for each block allocated.

    The value of alignment must be a power of 2 between 4 and 512.
    This is an optional argument. If alignment is not specified, a
    default of 8 (quadword alignment) is used.

 page-limit

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

    Maximum page limit. The page-limit argument is the address of a
    longword integer that specifies the maximum number of (512-byte)
    pages on VAX systems or pagelets on Alpha and I64 systems that
    can be allocated for the zone. The value of page-limit must be
    greater than or equal to 0. Note that part of the zone is used
    for header information.

    This is an optional argument. If page-limit is not specified
    or is specified as 0, the only limit is the total process
    virtual address space limit imposed by OpenVMS. If page-limit
    is specified, then initial-size must also be specified.

 smallest-block-size

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

    Smallest block size. The smallest-block-size argument is the
    address of a longword integer that specifies the smallest block
    size (in bytes) that has a lookaside list for the quick fit
    algorithm.

    If smallest-block-size is not specified, the default of block-
    size is used. That is, lookaside lists are provided for the first
    n multiples of block-size.

 zone-name

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

    Name to be associated with the zone being created. The optional
    zone-name argument is the address of a descriptor pointing to the
    zone name. If zone-name is not specified, the zone will not have
    an associated name.

 get-page

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by value

    Routine that allocates memory. The number and type of the
    arguments to this routine must match those of the LIB$GET_VM_
    PAGE routine. If get-page is not specified or is specified as 0,
    the LIB$GET_VM_PAGE routine is used to allocate memory.

 free-page

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by value

    Routine that deallocates memory. The number and type of the
    arguments to this routine must match those of the LIB$FREE_
    VM_PAGE routine. If free-page is not specified or if free-
    page is specified as 0, the LIB$FREE_VM_PAGE routine is used
    to deallocate memory.

2.24  –  LIB$CREATE_VM_ZONE_64

    (Alpha and I64 only.) The Create a New Zone routine creates a new
    storage zone in the 64-bit virtual address space, according to
    specified arguments.

    Format

      LIB$CREATE_VM_ZONE_64  zone-id [,algorithm]

                             [,algorithm-argument] [,flags]

                             [,extend-size] [,initial-size]

                             [,block-size] [,alignment] [,page-limit]

                             [,smallest-block-size] [,zone-name]

                             [,get-page] [,free-page]

2.24.1  –  Returns

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

2.24.2  –  Arguments

 zone-id

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Zone identifier. The zone-id argument is the address of a
    quadword that is set to the zone identifier of the newly created
    zone.

 algorithm

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Algorithm. The algorithm argument is the address of a quadword
    integer that represents the code for one of the LIB$VM
    algorithms. Use one of the following predefined symbols to
    specify this value:

    Symbol                  Value  Algorithm

    LIB$K_VM_FIRST_FIT      1      First fit
    LIB$K_VM_QUICK_FIT      2      Quick fit, lookaside list
    LIB$K_VM_FREQ_SIZES     3      Frequent sizes, lookaside list
    LIB$K_VM_FIXED          4      Fixed-size blocks

    If algorithm is not specified, a default of 1 (first fit) is
    used.

 algorithm-argument

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Algorithm argument. The algorithm-argument argument is the
    address of a quadword integer that contains a value specific
    to the particular allocation algorithm.

    Algorithm      Value

    First fit      Not used, may be omitted.
    Quick fit      The number of lookaside lists used. The number of
                   lists must be between 1 and 128.
    Frequent       The number of lookaside lists used. The number of
    sizes          lists must be between 1 and 16.
    Fixed size     The fixed request size (in bytes) for each get
    blocks         or free request. The request size must be greater
                   than 0.

    The algorithm-argument argument must be specified if you are
    using the quick-fit, frequent-sizes or fixed-size-blocks
    algorithms. However, this argument is optional, but ignored,
    if you are using the first-fit algorithm.

 flags

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Flags. The flags argument is the address of a quadword integer
    that contains flag bits that control various options, as follows:

    Bit  Value                 Description

    0    LIB$M_VM_BOUNDARY_    Boundary tags for faster freeing.
         TAGS
                               Adds a minimum of 16 bytes to each
                               block.
    1    LIB$M_VM_GET_FILL0    LIB$GET_VM_64; fill with bytes of 0.
    2    LIB$M_VM_GET_FILL1    LIB$GET_VM_64; fill with bytes of FF
                               (hexadecimal).
    3    LIB$M_VM_FREE_FILL0   LIB$FREE_VM_64; fill with bytes of 0.
    4    LIB$M_VM_FREE_FILL1   LIB$FREE_VM_64; fill with bytes of FF
                               (hexadecimal).
    5    LIB$M_VM_EXTEND_      Adds extents to existing areas if
         AREA                  possible.
    6    LIB$M_VM_NO_EXTEND    Prevents zone from being extended
                               beyond its initial size. If you
                               specify this flag, you must also
                               specify an initial-size. Extend-size
                               is not used.
    7    LIB$M_VM_TAIL_LARGE   Adds areas larger than extend-size
                               areas to the end of the area list.
                               Allocations that are larger than
                               extend-size can result in new areas.
                               These areas are added to the end of
                               the area list. (This provides better
                               memory re-use when allocating small
                               and very large blocks from the same
                               zone.)

    Bits 8 through 63 are reserved and must be 0.

    This is an optional argument. If flags is omitted, the default of
    0 (no fill and no boundary tags) is used.

 extend-size

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Zone extend size. The extend-size argument is the address of
    a quadword integer that contains the number of Alpha and I64
    pagelets to be added to the zone each time it is extended.

    The value of extend-size must be greater than or equal to 1.

    This is an optional argument. If extend-size is not specified, a
    default of 16 Alpha or I64 pagelets is used.

                                   NOTE

       The extend-size argument does not limit the number of blocks
       that can be allocated from the zone. The actual extension
       size is the greater of extend-size and the number of Alpha
       or I64 pagelets needed to satisfy the LIB$GET_VM_64 call
       that caused the extension.

 initial-size

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Initial size for the zone. The initial-size argument is the
    address of a quadword integer that contains the number of Alpha
    or I64 pagelets to be allocated for the zone as the zone is
    created.

    This is an optional argument. If you specify a value for initial-
    size, the value must be greater than or equal to 0; otherwise,
    LIB$_INVARG is returned. If initial-size is not specified or is
    specified as 0, no Alpha pagelets or I64 are allocated when the
    zone is created. The first call to LIB$GET_VM_64 for the zone
    allocates extend-size pagelets on Alpha or I64 systems.

 block-size

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Block size of the zone. The block-size argument is the address of
    a quadword integer specifying the allocation quantum (in bytes)
    for the zone. All blocks allocated are rounded up to a multiple
    of block-size.

    The value of block-size must be a power of 2 between 16 and 512.
    This is an optional argument. If block-size is not specified, a
    default of 16 is used.

 alignment

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Block alignment. The alignment argument is the address of a
    quadword integer that specifies the required address alignment
    (in bytes) for each block allocated.

    The value of alignment must be a power of 2 between 8 and 512.
    This is an optional argument. If alignment is not specified, a
    default of 16 (octaword alignment) is used.

 page-limit

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Maximum page limit. The page-limit argument is the address of a
    quadword integer that specifies the maximum number of Alpha or
    I64 pagelets that can be allocated for the zone. The value of
    page-limit must be greater than or equal to 0. Note that part of
    the zone is used for header information.

    This is an optional argument. If page-limit is not specified
    or is specified as 0, the only limit is the total process
    virtual address space limit imposed by OpenVMS. If page-limit
    is specified, then initial-size must also be specified.

 smallest-block-size

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Smallest block size. The smallest-block-size argument is the
    address of a quadword integer that specifies the smallest block
    size (in bytes) that has a lookaside list for the quick fit
    algorithm.

    If smallest-block-size is not specified, the default of block-
    size is used. That is, lookaside lists are provided for the first
    n multiples of block-size.

 zone-name

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

    Name to be associated with the zone being created. The optional
    zone-name argument is the address of a descriptor pointing to the
    zone name. If zone-name is not specified, the zone will not have
    an associated name.

 get-page

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by value

    Routine that allocates memory. The number and type of the
    arguments to this routine must match those of the LIB$GET_VM_
    PAGE_64 routine. If get-page is not specified or is specified as
    0, the LIB$GET_VM_PAGE_64 routine is used to allocate memory.

 free-page

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by value

    Routine that deallocates memory. The number and type of the
    arguments to this routine must match those of the LIB$FREE_VM_
    PAGE_64 routine. If free-page is not specified or if free-page
    is specified as 0, the LIB$FREE_VM_PAGE_64 routine is used to
    deallocate memory.

2.25  –  LIB$CRF_INS_KEY

    The Insert Key in Cross-Reference Table routine inserts
    information about a key into a cross-reference table.

    Format

      LIB$CRF_INS_KEY  control-table ,key-string ,symbol-value ,flags

2.25.1  –  Returns

    None.

2.25.2  –  Arguments

 control-table

    OpenVMS usage:vector_longword_signed
    type:         longword integer (signed)
    access:       read only
    mechanism:    by reference, array reference

    Cross-reference table into which LIB$CRF_INS_KEY inserts
    information about the key. The control-table argument is the
    address of a signed longword integer pointing to the cross-
    reference table. You must name this table each time you call a
    cross-reference routine because you can accumulate information
    for more than one cross-reference table at a time.

 key-string

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

    A counted ASCII string that contains a symbol name or an unsigned
    binary longword. The key-string argument is the address of a
    descriptor pointing to the key.

 symbol-value

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

    Symbol value, the address of which LIB$CRF_INS_KEY inserts in the
    cross-reference table. The symbol-value argument is the address
    of a signed longword integer containing this value. Both the key
    and value addresses must be permanent addresses in the user's
    symbol table.

 flags

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

    Value used in selecting the contents of the KEY2 and VAL2 fields;
    flags is stored with the entry. The flags argument is the address
    of an unsigned longword containing the flags. When preparing the
    output line, LIB$CRF_OUTPUT uses flags and the 16-bit mask in the
    field descriptor table to extract the data. The high-order bit of
    the word is reserved for LIB$CRF_INS_KEY.

2.26  –  LIB$CRF_INS_REF

    The Insert Reference to a Key in the Cross-Reference Table
    routine inserts a reference to a key in a cross-reference symbol
    table.

    Format

      LIB$CRF_INS_REF  control-table ,longword-integer-key

                       ,reference-string ,longword-integer-reference

                       ,ref-definition-indicator

2.26.1  –  Returns

    None.

2.26.2  –  Arguments

 control-table

    OpenVMS usage:vector_longword_signed
    type:         longword integer (signed)
    access:       read only
    mechanism:    by reference, array reference

    Control table associated with this cross-reference. The control-
    table argument is the address of an array containing the control
    table.

 longword-integer-key

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

    Key referred to by LIB$CRF_INS_REF. The longword-integer-key
    argument is the address of a signed longword integer containing
    the key. The key is a counted ASCII string that contains a symbol
    name or an unsigned binary longword. It must be a permanent
    address in the user's symbol table.

 reference-string

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

    Counted ASCII string with a maximum of 31 characters, not
    including the byte count. The reference-string argument is the
    address of a descriptor pointing to the counted ASCII string.

 longword-integer-reference

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

    The 16-bit value used in selecting the contents of the REF1
    field. The longword-integer-reference argument is the address of
    a signed longword integer containing this value. When preparing
    the output line, LIB$CRF_OUTPUT uses longword-integer-reference
    and the bit mask in the field descriptor table to extract the
    data. The high-order bit of the word is reserved for LIB$CRF_INS_
    REF.

 ref-definition-indicator

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

    Reference/definition indicator that LIB$CRF_INS_REF uses to
    distinguish between a reference to a symbol and the definition of
    the symbol. The ref-definition-indicator argument is the address
    of a signed longword integer containing this indicator. The only
    difference between processing a symbol reference and a symbol
    definition is where LIB$CRF_INS_REF stores the information.

    The reference/definition indicator can have either of the
    following values:

    Symbolic
    Name        Description

    CRF$K_REF   Reference to a symbol
    CRF$K_DEF   Definition of a symbol

2.27  –  LIB$CRF_OUTPUT

    The Output Cross-Reference Table Information routine extracts
    the information from the cross-reference tables and formats the
    output pages.

    Format

      LIB$CRF_OUTPUT  control-table ,output-line-width ,page1 ,page2

                      ,mode-indicator ,delete-save-indicator

2.27.1  –  Returns

    None.

2.27.2  –  Arguments

 control-table

    OpenVMS usage:vector_longword_signed
    type:         longword integer (signed)
    access:       read only
    mechanism:    by reference, array reference

    Control table associated with the cross-reference. The control-
    table argument is the address of an array containing the control
    table. The table contains the address of the user-supplied
    routine that prints the lines formatted by LIB$CRF_OUTPUT.

 output-line-width

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

    Width of the output line. The output-line-width argument is the
    address of a signed longword integer containing the width.

 page1

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

    Number of lines on the first page of the output. The page1
    argument is the address of a signed longword integer containing
    this number. This allows the user to reserve space to print
    header information on the first page of the cross-reference.

 page2

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

    Number of lines per page for the other pages. The page2 argument
    is the address of a signed longword integer containing this
    number.

 mode-indicator

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

    Output mode indicator. The mode-indicator argument is the address
    of a signed longword integer containing the mode indicator.

    This indicator allows the user to select which of three output
    modes is desired.

    Output Mode     Description

    CRF$K_VALUES    Only the value and key fields are to be printed.
                    LIB$CRF_OUTPUT creates multiple columns across
                    the page. Each column consists of the KEY1, KEY2,
                    VAL1, and VAL2 fields. A minimum of one space
                    between each column is guaranteed.
    CRF$K_VALS_     Requests a cross-reference summary that has no
    REFS            column space saved for a defining reference. If
                    the user inserted a reference with the CRF$K_DEF
                    indicator, the entry is ignored.
    CRF$K_DEFS_     Requests a cross-reference summary with the first
    REFS            REF1 and REF2 fields used only for definition
                    references. If no definition reference is
                    provided, the fields are filled with spaces.

 delete-save-indicator

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

    Delete/save indicator, which LIB$CRF_OUTPUT uses to determine
    whether the table's built-in accumulating symbol information
    is to be saved or deleted once the cross-reference is produced.
    The delete-save-indicator argument is the address of a signed
    longword integer containing the delete/save indicator.

    The indicator can be either of the following:

    CRF$K_SAVE   To preserve the tables for subsequent processing
    CRF$K_       To delete the tables
    DELETE

2.28  –  LIB$CURRENCY

    The Get System Currency Symbol routine returns the system's
    currency symbol.

    Format

      LIB$CURRENCY  currency-string [,resultant-length]

2.28.1  –  Returns

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

2.28.2  –  Arguments

 currency-string

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

    Currency symbol. The currency-string argument is the address of a
    descriptor pointing to the currency symbol.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of characters that LIB$CURRENCY has written into the
    currency-string argument, not counting padding in the case of a
    fixed-length string. The resultant-length argument is the address
    of an unsigned word containing the length of the currency symbol.
    If the input string is truncated to the size specified in the
    currency-string argument, resultant-length is set to this size.
    Therefore, resultant-length can always be used by the calling
    program to access a valid substring of currency-string.

2.29  –  LIB$CVTF_FROM_INTERNAL_TIME

    The Convert Internal Time to External Time (F-Floating-Point
    Value) routine converts a delta internal OpenVMS system time into
    an external F-floating time.

    Format

      LIB$CVTF_FROM_INTERNAL_TIME  operation ,resultant-time

                                   ,input-time

2.29.1  –  Returns

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

2.29.2  –  Arguments

 operation

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

    The conversion to be performed. The operation argument is the
    address of an unsigned longword specifying the operation. Valid
    values for operation are the following:

    Operation              Interpretation

    LIB$K_DELTA_WEEKS_F    Fractional weeks
    LIB$K_DELTA_DAYS_F     Fractional days
    LIB$K_DELTA_HOURS_F    Fractional hours
    LIB$K_DELTA_MINUTES_F  Fractional minutes
    LIB$K_DELTA_SECONDS_F  Fractional seconds

 resultant-time

    OpenVMS usage:floating_point
    type:         F_floating
    access:       write only
    mechanism:    by reference

    The external time that results from the conversion. The
    resultant-time argument is the address of an F-floating-point
    value containing the result.

 input-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Delta time to be converted. The input-time argument is the
    address of an unsigned quadword containing the time.

2.30  –  LIB$CVTS_FROM_INTERNAL_TIME

    (Alpha and I64 only.) The Convert Internal Time to External Time
    (IEEE S-Floating-Point Value) routine converts a delta internal
    OpenVMS system time into an external IEEE S-floating time.

    Format

      LIB$CVTS_FROM_INTERNAL_TIME  operation ,resultant-time

                                   ,input-time

2.30.1  –  Returns

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

2.30.2  –  Arguments

 operation

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

    The conversion to be performed. The operation argument is the
    address of an unsigned longword specifying the operation. Valid
    values for operation are the following:

    Operation              Interpretation

    LIB$K_DELTA_WEEKS_F    Fractional weeks
    LIB$K_DELTA_DAYS_F     Fractional days
    LIB$K_DELTA_HOURS_F    Fractional hours
    LIB$K_DELTA_MINUTES_F  Fractional minutes
    LIB$K_DELTA_SECONDS_F  Fractional seconds

 resultant-time

    OpenVMS usage:floating_point
    type:         IEEE S_floating
    access:       write only
    mechanism:    by reference

    The external time that results from the conversion. The
    resultant-time argument is the address of an IEEE S-floating-
    point value containing the result.

 input-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Delta time to be converted. The input-time argument is the
    address of an unsigned quadword containing the time.

2.31  –  LIB$CVTF_TO_INTERNAL_TIME

    The Convert External Time to Internal Time (F-Floating-Point
    Value) routine converts an external time interval into an OpenVMS
    internal format F-floating delta time.

    Format

      LIB$CVTF_TO_INTERNAL_TIME  operation ,input-time

                                 ,resultant-time

2.31.1  –  Returns

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

2.31.2  –  Arguments

 operation

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

    The conversion to be performed. The operation argument is the
    address of an unsigned longword specifying the operation. Valid
    values for operation are the following:

    Operation              Interpretation

    LIB$K_DELTA_WEEKS_F    Fractional weeks
    LIB$K_DELTA_DAYS_F     Fractional days
    LIB$K_DELTA_HOURS_F    Fractional hours
    LIB$K_DELTA_MINUTES_F  Fractional minutes
    LIB$K_DELTA_SECONDS_F  Fractional seconds

 input-time

    OpenVMS usage:varying_arg
    type:         F_floating
    access:       read only
    mechanism:    by reference

    Delta time to be converted. The input-time argument is the
    address of this input time. The value you supply for input-time
    must be greater than 0.

 resultant-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    The OpenVMS internal format delta time that results from the
    conversion. The resultant-time argument is the address of an
    unsigned quadword containing the result.

2.32  –  LIB$CVTS_TO_INTERNAL_TIME

    (Alpha and I64 only.) The Convert External Time to Internal Time
    (IEEE S-Floating-Point Value) routine converts an external time
    interval into an OpenVMS internal format IEEE S-floating delta
    time.

    Format

      LIB$CVTS_TO_INTERNAL_TIME  operation ,input-time

                                 ,resultant-time

2.32.1  –  Returns

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

2.32.2  –  Arguments

 operation

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

    The conversion to be performed. The operation argument is the
    address of an unsigned longword specifying the operation. Valid
    values for operation are the following:

    Operation              Interpretation

    LIB$K_DELTA_WEEKS_F    Fractional weeks
    LIB$K_DELTA_DAYS_F     Fractional days
    LIB$K_DELTA_HOURS_F    Fractional hours
    LIB$K_DELTA_MINUTES_F  Fractional minutes
    LIB$K_DELTA_SECONDS_F  Fractional seconds

 input-time

    OpenVMS usage:varying_arg
    type:         IEEE S_floating
    access:       read only
    mechanism:    by reference

    Delta time to be converted. The input-time argument is the
    address of this input time. The value you supply for input-time
    must be greater than 0.

 resultant-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    The OpenVMS internal format delta time that results from the
    conversion. The resultant-time argument is the address of an
    unsigned quadword containing the result.

2.33  –  LIB$CVT_DX_DX

    The General Data Type Conversion routine converts OpenVMS
    standard atomic or string data described by a source descriptor
    to OpenVMS standard atomic or string data described by a
    destination descriptor. This conversion is supported over a
    subset of the OpenVMS standard data types.

    Format

      LIB$CVT_DX_DX  source-item ,destination-item

                     [,word-integer-dest-length]

2.33.1  –  Returns

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

2.33.2  –  Arguments

 source-item

    OpenVMS usage:unspecified
    type:         unspecified
    access:       read only
    mechanism:    by descriptor

    Source item to be converted by LIB$CVT_DX_DX. The source-item
    argument is the address of a descriptor pointing to the source
    item to be converted. The type of the item to be converted is
    contained in the descriptor.

 destination-item

    OpenVMS usage:unspecified
    type:         unspecified
    access:       write only
    mechanism:    by descriptor

    Destination of the conversion. The destination-item argument is
    the address of a descriptor pointing to the destination item.
    The destination descriptor specifies the data type to which the
    source item is converted.

 word-integer-dest-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length in bytes of the destination item (when that item is a
    string) that has been converted by LIB$CVT_DX_DX, not including
    any space filling. The word-integer-dest-length argument contains
    the address of an unsigned word containing this length.

    If the destination string is truncated, the returned length
    reflects the truncation. This word can be used by the calling
    program to determine if truncation has occurred or to extract
    the exact length of the string when the string contains space
    filling.

2.34  –  LIB$CVT_FROM_INTERNAL_TIME

    The Convert Internal Time to External Time routine converts an
    internal OpenVMS system time (either absolute or delta) into an
    external time.

    Format

      LIB$CVT_FROM_INTERNAL_TIME  operation ,resultant-time

                                  [,input-time]

2.34.1  –  Returns

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

2.34.2  –  Arguments

 operation

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

    The conversion to be performed. The operation argument is the
    address of an unsigned longword containing the operation. The
    following table shows valid values for operation:

    Operation               Type         Return Range

    LIB$K_MONTH_OF_YEAR     Absolute     1 to 12
    LIB$K_DAY_OF_YEAR       Absolute     1 to 366
    LIB$K_HOUR_OF_YEAR      Absolute     1 to 8784
    LIB$K_MINUTE_OF_YEAR    Absolute     1 to 527,040
    LIB$K_SECOND_OF_YEAR    Absolute     1 to 31,622,400
    LIB$K_DAY_OF_MONTH      Absolute     1 to 31
    LIB$K_HOUR_OF_MONTH     Absolute     1 to 744
    LIB$K_MINUTE_OF_MONTH   Absolute     1 to 44,640
    LIB$K_SECOND_OF_MONTH   Absolute     1 to 2,678,400
    LIB$K_DAY_OF_WEEK       Absolute     1 to 7
    LIB$K_HOUR_OF_WEEK      Absolute     1 to 168
    LIB$K_MINUTE_OF_WEEK    Absolute     1 to 10,080
    LIB$K_SECOND_OF_WEEK    Absolute     1 to 604,800
    LIB$K_HOUR_OF_DAY       Absolute     0 to 23
    LIB$K_MINUTE_OF_DAY     Absolute     0 to 1439
    LIB$K_SECOND_OF_DAY     Absolute     0 to 86,399
    LIB$K_MINUTE_OF_HOUR    Absolute     0 to 59
    LIB$K_SECOND_OF_HOUR    Absolute     0 to 3599
    LIB$K_SECOND_OF_MINUTE  Absolute     0 to 59
    LIB$K_JULIAN_DATE       Absolute     Julian date
    LIB$K_DELTA_WEEKS       Delta
    LIB$K_DELTA_DAYS        Delta
    LIB$K_DELTA_HOURS       Delta
    LIB$K_DELTA_MINUTES     Delta
    LIB$K_DELTA_SECONDS     Delta

 resultant-time

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

    The external time that results from the conversion. The
    resultant-time argument is the address of an unsigned longword
    containing the result.

 input-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional absolute or delta time to be converted. The input-time
    argument is the address of an unsigned quadword containing the
    time. If you do not supply a value for input-time, the current
    system time is used.

2.35  –  LIB$CVT_TO_INTERNAL_TIME

    The Convert External Time to Internal Time routine converts an
    external time interval into an OpenVMS internal format delta
    time.

    Format

      LIB$CVT_TO_INTERNAL_TIME  operation ,input-time ,resultant-time

2.35.1  –  Returns

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

2.35.2  –  Arguments

 operation

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

    The conversion to be performed. The operation argument is the
    address of an unsigned longword specifying the operation. Valid
    values for operation are the following:

    Operation              Interpretation

    LIB$K_DELTA_WEEKS      Whole weeks in delta time
    LIB$K_DELTA_DAYS       Whole days in delta time
    LIB$K_DELTA_HOURS      Whole hours in delta time
    LIB$K_DELTA_MINUTES    Whole minutes in delta time
    LIB$K_DELTA_SECONDS    Whole seconds in delta time

 input-time

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

    Delta time to be converted. The input-time argument is the
    address of this input time. The value you supply for input-time
    must be greater than 0.

 resultant-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    The OpenVMS internal format delta time that results from the
    conversion. The resultant-time argument is the address of an
    unsigned quadword containing the result.

2.36  –  LIB$CVT_VECTIM

    The Convert 7-Word Vector to Internal Time routine converts a
    7-word vector into an OpenVMS internal format delta or absolute
    time.

    Format

      LIB$CVT_VECTIM  input-time ,resultant-time

2.36.1  –  Returns

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

2.36.2  –  Arguments

 input-time

    OpenVMS usage:vector_word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference, array reference

    Time to be converted. The input-time argument is the address of
    a 7-word structure containing this time. This vector directly
    corresponds to a $NUMTIM timbuf structure.

    The input-time argument can represent an absolute or a delta
    time. In order for input-time to represent a delta time, the year
    since 0 and month of year fields must equal zero. If those fields
    do not equal zero, an absolute time is returned.

 resultant-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    The OpenVMS internal format delta or absolute time that results
    from the conversion. The resultant-time argument is the address
    of an unsigned quadword containing the result.

2.37  –  LIB$CVT xTB

    The Convert Numeric Text to Binary routines return a binary
    representation of the ASCII text string representation of a
    decimal, hexadecimal, or octal number.

    Format

      LIB$CVT_DTB  byte-count ,numeric-string ,result

      LIB$CVT_HTB  byte-count ,numeric-string ,result

      LIB$CVT_OTB  byte-count ,numeric-string ,result

2.37.1  –  Returns

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

2.37.2  –  Arguments

 byte-count

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

    Byte count of the input ASCII text string. The byte-count
    argument is a signed longword integer containing the byte count
    of the input string.

 numeric-string

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

    ASCII text string representation of a decimal, hexadecimal, or
    octal number that LIB$CVT_xTB converts to binary representation.
    The numeric-string argument is the address of a character string
    containing this input string to be converted.

    LIB$CVT_xTB allows only an optional plus (+) or minus (-) sign
    followed by a string of decimal, hexadecimal, or octal characters
    appropriate to the routine being called.

 result

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

    Binary representation of the input string. The result argument is
    the address of a signed longword integer containing the converted
    string.

2.38  –  LIB$CVT xTB 64

    (Alpha and I64 only.) The Convert Numeric Text to Binary
    routines return a binary representation of the ASCII text string
    representation of a decimal, hexadecimal, or octal number.

    Format

      LIB$CVT_DTB_64  byte-count ,numeric-string ,result

      LIB$CVT_HTB_64  byte-count ,numeric-string ,result

      LIB$CVT_OTB_64  byte-count ,numeric-string ,result

2.38.1  –  Returns

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

2.38.2  –  Arguments

 byte-count

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

    Byte count of the input ASCII text string. The byte-count
    argument is a signed longword integer containing the byte count
    of the input string.

 numeric-string

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

    ASCII text string representation of a decimal, hexadecimal,
    or octal number that LIB$CVT_xTB_64 converts to binary
    representation. The numeric-string argument is the address of
    a character string containing this input string to be converted.

    LIB$CVT_xTB_64 allows only an optional plus (+) or minus (-) sign
    followed by a string of decimal, hexadecimal, or octal characters
    appropriate to the routine being called.

 result

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       write only
    mechanism:    by reference

    Binary representation of the input string. The result argument is
    the address of a signed quadword integer containing the converted
    string.

2.39  –  LIB$DATE_TIME

    The Date and Time Returned as a String routine returns the
    OpenVMS system date and time in the semantics of a user-provided
    string.

    Format

      LIB$DATE_TIME  date-time-string

2.39.1  –  Returns

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

2.39.2  –  Argument

 date-time-string

    OpenVMS usage:time_name
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which LIB$DATE_TIME writes the system
    date and time. The date-time-string argument is the address of a
    descriptor pointing to the destination string. This string is 23
    characters long; its format is as follows:

    dd-mmm-yyyy hh:mm:ss.hh

    See the VSI OpenVMS Programming Concepts Manual for a description
    of system date and time operations as well as a detailed
    description of the format mnemonics used in these routines.

2.40  –  LIB$DAY

    The Day Number Returned as a Longword Integer routine returns the
    number of days since the system zero date of November 17, 1858,
    or the number of days from November 17, 1858, to a user-supplied
    date.

    Format

      LIB$DAY  number-of-days [,user-time] [,day-time]

2.40.1  –  Returns

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

2.40.2  –  Arguments

 number-of-days

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

    Number of days since the system zero date. The number-of-days
    argument is the address of a signed longword integer containing
    the day number.

 user-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    User-supplied time, in 100-nanosecond units. The user-time
    argument is the address of a signed quadword integer containing
    the user time. A positive value indicates an absolute time, while
    a negative value indicates a delta time. This is an optional
    argument. If user-time is omitted, the default is the current
    system time. This quadword time value is obtained by calling the
    $BINTIM system service.

    If time is passed as zero by value, the numeric value for
    the current day is returned. If time is passed as a zero by
    reference, the number returned represents the day of November
    17, 1858, rather than the current day.

 day-time

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

    Number of 10-millisecond units since midnight of the user-time
    argument. The day-time argument is the address of a signed
    longword integer into which LIB$DAY writes this number of units.

2.41  –  LIB$DAY_OF_WEEK

    The Show Numeric Day of Week routine returns the numeric day of
    the week for an input time value. If 0 is the input time value,
    the current day of the week is returned. The days are numbered 1
    through 7, with Monday as day 1 and Sunday as day 7.

    Format

      LIB$DAY_OF_WEEK  [user-time,] day-number

2.41.1  –  Returns

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

2.41.2  –  Arguments

 user-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Time to be translated to a day of the week, or zero. The
    optional user-time argument is the address of an unsigned
    quadword containing the value of time. Time must be supplied
    as an absolute system time. To obtain this time value in proper
    quadword format, call the $BINTIM system service.

    If time is passed as zero by value, the numeric value for
    the current day is returned. If time is passed as a zero by
    reference, the number returned represents the day of November
    17, 1858. If the user-time argument is omitted, it is equivalent
    to passing a zero by value.

 day-number

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

    Numeric day of week. The day-number argument is the address of
    a longword into which LIB$DAY_OF_WEEK writes the integer value
    representing the day of the week.

2.42  –  LIB$DECODE_FAULT

    The Decode Instruction Stream During Fault routine is a tool
    for building condition handlers that process instruction fault
    exceptions. It is called from a condition handler.

    This routine is not available to native OpenVMS Alpha and I64
    programs but is available to translated VAX images.

    Format

      LIB$DECODE_FAULT  signal-arguments ,mechanism-arguments

                        ,user-procedure [,unspecified-user-argument]

                        [,instruction-definitions]

2.42.1  –  Returns

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

2.42.2  –  Arguments

 signal-arguments

    OpenVMS usage:vector_longword_unsigned
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Signal arguments array that was passed from the OpenVMS operating
    system to your condition handler. The signal-arguments argument
    is the address of the signal arguments array.

 mechanism-arguments

    OpenVMS usage:vector_longword_unsigned
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Mechanism arguments array that was passed from OpenVMS to your
    condition handler. The mechanism-arguments argument is the
    address of the mechanism arguments array.

 user-procedure

    OpenVMS usage:procedure
    type:         procedure value
    access:       call after stack unwind
    mechanism:    by descriptor, procedure descriptor

    User-supplied action routine that LIB$DECODE_FAULT calls to
    handle the exception. The user-procedure argument is the address
    of a descriptor pointing to your user action routine. The user-
    procedure argument may be of type "procedure value" when called
    by languages with up-level addressing. If user-procedure is not
    of type "bound routine value," it is assumed to be the address of
    an entry mask.

 unspecified-user-argument

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

    Additional information passed from your handler without
    interpretation to your user action routine. The unspecified-
    user-argument argument contains the value of this additional
    information. The unspecified-user-argument argument is optional;
    if it is omitted, zero is used as the default.

 instruction-definitions

    OpenVMS usage:vector_byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference, array reference

    Array of bytes specifying instruction opcodes and operand
    definitions that are to replace or supplement the standard
    instruction definitions. The instruction-definitions argument
    is the address of this array.

    If instruction-definitions is omitted, only the standard
    instruction definitions are used. If supplied, instruction-
    definitions is searched first, followed by the standard
    definitions.

    Each instruction definition consists of a series of bytes, the
    first one or two of which is the instruction opcode. If the
    instruction is a 2-byte opcode, the escape byte, which must
    be hex FD, FE, or FF, is placed in the first of the two bytes.
    Following the opcode may be from 0 to 16 operand definition
    bytes. These bytes indicate the operand's access type and data
    type.

    The end of each instruction definition is denoted by a byte
    containing the value LIB$K_DCFOPR_END (zero). The list of
    instruction definitions is terminated by two bytes, each of which
    contains the value -1 (hexadecimal FF).

2.43  –  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.

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

    Format

      LIB$DEC_OVER  new-setting

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

2.43.2  –  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.

2.44  –  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]

2.44.1  –  Returns

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

2.44.2  –  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. If running on
    Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set, the string
    must not contain more characters than specified by NAML$C_MAXRSS,
    otherwise the string must not contain more than 255 characters.
    Any string class is supported.

 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.

 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.

 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.

 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:

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

    o  (Alpha and I64 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 VSI.
    1                       Reserved to VSI.
    2    LIB$M_FIL_LONG_    (Alpha or I64 only) If set, LIB$DELETE_
         NAMES              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).

2.45  –  LIB$DELETE_LOGICAL

    The Delete Logical Name routine requests the calling process'
    command language interpreter (CLI) to delete a supervisor-mode
    process logical name. LIB$DELETE_LOGICAL provides the same
    function as the DCL command DEASSIGN.

    Format

      LIB$DELETE_LOGICAL  logical-name [,table-name]

2.45.1  –  Returns

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

2.45.2  –  Arguments

 logical-name

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

    Logical name to be deleted. The logical-name argument is the
    address of a descriptor pointing to this logical name string. The
    maximum length of a logical name is 255 characters.

 table-name

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

    Name of the table from which the logical name is to be deleted.
    The table-name argument is the address of a descriptor pointing
    to this name string. This is an optional argument. If the
    argument is omitted, the LNM$PROCESS table is used.

2.46  –  LIB$DELETE_SYMBOL

    The Delete CLI Symbol routine requests the calling process's
    command language interpreter (CLI) to delete an existing CLI
    symbol.

    Format

      LIB$DELETE_SYMBOL  symbol [,table-type-indicator]

2.46.1  –  Returns

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

2.46.2  –  Arguments

 symbol

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

    Name of the symbol to be deleted by LIB$DELETE_SYMBOL. The symbol
    argument is the address of a descriptor pointing to this symbol
    string. The symbol name is converted to uppercase, and trailing
    blanks are removed before use.

    Symbol must begin with a letter, a digit, a dollar sign ($),  a
    hyphen (-),  or an underscore (_). The maximum length of symbol
    is 255 characters.

 table-type-indicator

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

    Indicator of the table that contains the symbol to be deleted.
    The table-type-indicator argument is the address of a signed
    longword integer that is this table indicator.

    If table-type-indicator is omitted, the local symbol table is
    used. The following are possible values for the table-type-
    indicator argument:

    Symbolic Name       Value Table Used

    LIB$K_CLI_LOCAL_    1     Local symbol table
    SYM
    LIB$K_CLI_GLOBAL_   2     Global symbol table
    SYM

2.47  –  LIB$DELETE_VM_ZONE

    The Delete Virtual Memory Zone routine deletes a zone from the
    32-bit virtual address space and returns all pages on VAX systems
    or pagelets on Alpha and I64 systems owned by the zone to the
    processwide 32-bit page pool.

    Format

      LIB$DELETE_VM_ZONE  zone-id

2.47.1  –  Returns

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

2.47.2  –  Argument

 zone-id

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

    Zone identifier. The zone-id is the address of a longword that
    contains the identifier of a zone created by a previous call to
    LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE.

2.48  –  LIB$DELETE_VM_ZONE_64

    (Alpha and I64 only.) The Delete Virtual Memory Zone routine
    deletes a zone from the 64-bit virtual address space and returns
    all Alpha and I64 system pagelets owned by the zone to the
    processwide 64-bit page pool.

    Format

      LIB$DELETE_VM_ZONE_64  zone-id

2.48.1  –  Returns

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

2.48.2  –  Argument

 zone-id

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Zone identifier. The zone-id is the address of a quadword that
    contains the identifier of a zone created by a previous call to
    LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64.

2.49  –  LIB$DIGIT_SEP

    The Get Digit Separator Symbol routine returns the system's digit
    separator symbol.

    Format

      LIB$DIGIT_SEP  digit-separator-string [,resultant-length]

2.49.1  –  Returns

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

2.49.2  –  Arguments

 digit-separator-string

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

    Digit separator symbol returned by LIB$DIGIT_SEP. The digit-
    separator-string argument is the address of a descriptor pointing
    to the digit separator.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of characters written into digit-separator-string, not
    counting padding in the case of a fixed-length string. The
    resultant-length argument is the address of an unsigned word
    containing the length of the digit separator symbol. If the
    input string is truncated to the size specified in the digit-
    separator-string descriptor, resultant-length is set to this
    size. Therefore, resultant-length can always be used by the
    calling program to access a valid substring of digit-separator-
    string.

2.50  –  LIB$DISABLE_CTRL

    The Disable CLI Interception of Control Characters routine
    requests the calling process's command language interpreter (CLI)
    to not intercept the selected control characters when they are
    entered during an interactive terminal session. LIB$DISABLE_CTRL
    provides the same function as the DCL command SET NOCONTROL.

    Format

      LIB$DISABLE_CTRL  disable-mask [,old-mask]

2.50.1  –  Returns

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

2.50.2  –  Arguments

 disable-mask

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

    Bit mask indicating which control characters are not to be
    intercepted. The disable-mask argument is the address of an
    unsigned longword containing this bit mask.

    Each of the 32 bits corresponds to one of the 32 possible control
    characters. If a bit is set, the corresponding control character
    is no longer intercepted by the CLI. Currently, only bits 20 and
    25, corresponding to Ctrl/T and Ctrl/Y, are recognized.

    The following mask is defined in symbol libraries supplied by VSI
    to specify the value of disable-mask:

    Symbol          Hex Value     Function

    LIB$M_CLI_      %X'00100000'  Disables Ctrl/T
    CTRLT
    LIB$M_CLI_      %X'02000000'  Disables Ctrl/Y
    CTRLY

    If a set bit does not correspond to a character that the CLI can
    intercept, LIB$DISABLE_CTRL returns an error.

 old-mask

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

    Previous bit mask. The old-mask argument is the address of an
    unsigned longword into which LIB$DISABLE_CTRL writes the old bit
    mask. The old bit mask is of the same form as disable-mask and
    indicates those control characters that were previously enabled.
    It may therefore be given to LIB$ENABLE_CTRL to reinstate the
    previous condition.

2.51  –  LIB$DO_COMMAND

    The Execute Command routine stops program execution and directs
    the command language interpreter (CLI) to execute a command
    that you supply as the argument. If successful, LIB$DO_COMMAND
    does not return control to the calling program. Instead, LIB$DO_
    COMMAND begins execution of the specified command.

    If you want control to return to the caller, use LIB$SPAWN
    instead.

    Format

      LIB$DO_COMMAND  command-string

2.51.1  –  Returns

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

2.51.2  –  Argument

 command-string

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

    Text of the command that LIB$DO_COMMAND executes. The command-
    string argument is the address of a descriptor pointing to
    the command text. The maximum length of the command is 255
    characters.

2.52  –  LIB$EDIV

    The Extended-Precision Divide routine performs extended-precision
    division. LIB$EDIV makes the VAX EDIV instruction available as a
    callable routine.

    Format

      LIB$EDIV  longword-integer-divisor ,quadword-integer-dividend

                ,longword-integer-quotient ,remainder

2.52.1  –  Returns

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

2.52.2  –  Arguments

 longword-integer-divisor

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

    Divisor. The longword-integer-divisor argument is the address of
    a signed longword integer containing the divisor.

 quadword-integer-dividend

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Dividend. The quadword-integer-dividend argument is the address
    of a signed quadword integer containing the dividend.

 longword-integer-quotient

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

    Quotient. The longword-integer-quotient argument is the address
    of a signed longword integer containing the quotient.

 remainder

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

    Remainder. The remainder argument is the address of a signed
    longword integer containing the remainder.

2.53  –  LIB$EMODD

    The Extended Multiply and Integerize routine (D-Floating-Point
    Values) allows higher-level language users to perform accurate
    range reduction of D-floating arguments.

    On Alpha and I64 systems, D-floating-point values are not
    supported in full precision in native OpenVMS Alpha and I64
    programs. They are precise to 56 bits on VAX systems, 53 or 56
    bits in translated VAX images, and 53 bits in native OpenVMS
    Alpha and I64 programs.

    Format

      LIB$EMODD  floating-point-multiplier ,multiplier-extension

                 ,floating-point-multiplicand ,integer-portion

                 ,fractional-portion

2.53.1  –  Returns

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

2.53.2  –  Arguments

 floating-point-multiplier

    OpenVMS usage:floating_point
    type:         D_floating
    access:       read only
    mechanism:    by reference

    The multiplier. The floating-point-multiplier argument is a D-
    floating number.

 multiplier-extension

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    The left-justified multiplier-extension bits. The multiplier-
    extension argument is an unsigned byte.

 floating-point-multiplicand

    OpenVMS usage:floating_point
    type:         D_floating
    access:       read only
    mechanism:    by reference

    The multiplicand. The floating-point-multiplicand argument is a
    D-floating number.

 integer-portion

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

    The integer portion of the result. The integer-portion argument
    is the address of a signed longword integer containing the
    integer portion of the result.

 fractional-portion

    OpenVMS usage:floating_point
    type:         D_floating
    access:       write only
    mechanism:    by reference

    The fractional portion of the result. The fractional-portion
    argument is a D-floating number.

2.54  –  LIB$EMODF

    The Extended Multiply and Integerize routine (F-Floating-Point
    Values) allows higher-level language users to perform accurate
    range reduction of F-floating arguments.

    Format

      LIB$EMODF  floating-point-multiplier ,multiplier-extension

                 ,floating-point-multiplicand ,integer-portion

                 ,fractional-portion

2.54.1  –  Returns

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

2.54.2  –  Arguments

 floating-point-multiplier

    OpenVMS usage:floating_point
    type:         F_floating
    access:       read only
    mechanism:    by reference

    The multiplier. The floating-point-multiplier argument is the
    address of an F-floating number containing the number.

 multiplier-extension

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    The left-justified multiplier-extension bits. The multiplier-
    extension argument is the address of an unsigned byte containing
    these multiplier extension bits.

 floating-point-multiplicand

    OpenVMS usage:floating_point
    type:         F_floating
    access:       read only
    mechanism:    by reference

    The multiplicand. The floating-point-multiplicand argument is an
    F-floating number.

 integer-portion

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

    The integer portion of the result. The integer-portion argument
    is the address of a signed longword integer containing the
    integer portion of the result.

 fractional-portion

    OpenVMS usage:floating_point
    type:         F_floating
    access:       write only
    mechanism:    by reference

    The fractional portion of the result. The fractional-portion
    argument is the address of an F-floating number containing the
    fractional portion of the result.

2.55  –  LIB$EMODG

    The Extended Multiply and Integerize routine (G-Floating-Point
    Values) allows higher-level language users to perform accurate
    range reduction of G-floating arguments.

    Format

      LIB$EMODG  floating-point-multiplier ,multiplier-extension

                 ,floating-point-multiplicand ,integer-portion

                 ,fractional-portion

2.55.1  –  Returns

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

2.55.2  –  Arguments

 floating-point-multiplier

    OpenVMS usage:floating_point
    type:         G_floating
    access:       read only
    mechanism:    by reference

    The multiplier. The floating-point-multiplier argument is a G-
    floating number.

 multiplier-extension

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    The left-justified multiplier-extension bits. The multiplier-
    extension argument is an unsigned word.

 floating-point-multiplicand

    OpenVMS usage:floating_point
    type:         G_floating
    access:       read only
    mechanism:    by reference

    The multiplicand. The floating-point-multiplicand argument is a
    G-floating number.

 integer-portion

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

    The integer portion of the result. The integer-portion argument
    is the address of a signed longword integer containing the
    integer portion of the result.

 fractional-portion

    OpenVMS usage:floating_point
    type:         G_floating
    access:       write only
    mechanism:    by reference

    The fractional portion of the result. The fractional-portion
    argument is a G-floating number.

2.56  –  LIB$EMODH

    On OpenVMS VAX systems, the Extended Multiply and Integerize
    routine (H-Floating-Point Values) allows higher-level language
    users to perform accurate range reduction of H-floating
    arguments.

    This routine is not available to native OpenVMS Alpha programs
    but is available to translated VAX images.

    Format

      LIB$EMODH  floating-point-multiplier ,multiplier-extension

                 ,floating-point-multiplicand ,integer-portion

                 ,fractional-portion

2.56.1  –  Returns

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

2.56.2  –  Arguments

 floating-point-multiplier

    OpenVMS usage:floating_point
    type:         H_floating
    access:       read only
    mechanism:    by reference

    The multiplier. The floating-point-multiplier argument is an
    H-floating number.

 multiplier-extension

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    The left-justified multiplier-extension bits. The multiplier-
    extension argument is an unsigned word.

 floating-point-multiplicand

    OpenVMS usage:floating_point
    type:         H_floating
    access:       read only
    mechanism:    by reference

    The multiplicand. The floating-point-multiplicand argument is an
    H-floating number.

 integer-portion

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

    The integer portion of the result. The integer-portion argument
    is the address of a signed longword integer containing the
    integer portion of the result.

 fractional-portion

    OpenVMS usage:floating_point
    type:         H_floating
    access:       write only
    mechanism:    by reference

    The fractional portion of the result. The fractional-portion
    argument is an H-floating number.

2.57  –  LIB$EMODS_

    (Alpha and I64 only.) The Extended Multiply and Integerize
    routine (IEEE S-Floating-Point Values) allows higher-level
    language users to perform accurate range reduction of IEEE S-
    floating arguments.

    Format

      LIB$EMODS  floating-point-multiplier ,multiplier-extension

                 ,floating-point-multiplicand ,integer-portion

                 ,fractional-portion

2.57.1  –  Returns

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

2.57.2  –  Arguments

 floating-point-multiplier

    OpenVMS usage:floating_point
    type:         IEEE S_floating
    access:       read only
    mechanism:    by reference

    The multiplier. The floating-point-multiplier argument is the
    address of an IEEE S-floating number containing the number.

 multiplier-extension

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    The left-justified multiplier-extension bits. The multiplier-
    extension argument is the address of an unsigned byte containing
    these multiplier extension bits.

 floating-point-multiplicand

    OpenVMS usage:floating_point
    type:         IEEE S_floating
    access:       read only
    mechanism:    by reference

    The multiplicand. The floating-point-multiplicand argument is an
    IEEE S-floating number.

 integer-portion

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

    The integer portion of the result. The integer-portion argument
    is the address of a signed longword integer containing the
    integer portion of the result.

 fractional-portion

    OpenVMS usage:floating_point
    type:         IEEE S_floating
    access:       write only
    mechanism:    by reference

    The fractional portion of the result. The fractional-portion
    argument is the address of an IEEE S-floating number containing
    the fractional portion of the result.

2.58  –  LIB$EMODT

    (Alpha and i64 only.) The Extended Multiply and Integerize
    routine (IEEE T-Floating-Point Values) allows higher-level
    language users to perform accurate range reduction of IEEE T-
    floating arguments.

    Format

      LIB$EMODT  floating-point-multiplier ,multiplier-extension

                 ,floating-point-multiplicand ,integer-portion

                 ,fractional-portion

2.58.1  –  Returns

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

2.58.2  –  Arguments

 floating-point-multiplier

    OpenVMS usage:floating_point
    type:         IEEE T_floating
    access:       read only
    mechanism:    by reference

    The multiplier. The floating-point-multiplier argument is the
    address of an IEEE T-floating number containing the number.

 multiplier-extension

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    The left-justified multiplier-extension bits. The multiplier-
    extension argument is the address of an unsigned byte containing
    these multiplier extension bits.

 floating-point-multiplicand

    OpenVMS usage:floating_point
    type:         IEEE T_floating
    access:       read only
    mechanism:    by reference

    The multiplicand. The floating-point-multiplicand argument is an
    IEEE T-floating number.

 integer-portion

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

    The integer portion of the result. The integer-portion argument
    is the address of a signed longword integer containing the
    integer portion of the result.

 fractional-portion

    OpenVMS usage:floating_point
    type:         IEEE T_floating
    access:       write only
    mechanism:    by reference

    The fractional portion of the result. The fractional-portion
    argument is the address of an IEEE T-floating number containing
    the fractional portion of the result.

2.59  –  LIB$EMUL

    The Extended-Precision Multiply routine performs extended-
    precision multiplication. LIB$EMUL makes the VAX EMUL instruction
    available as a callable routine.

    Format

      LIB$EMUL  longword-integer-multiplier

                ,longword-integer-multiplicand ,addend ,product

2.59.1  –  Returns

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

2.59.2  –  Arguments

 longword-integer-multiplier

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

    Multiplier used by LIB$EMUL in the extended-precision
    multiplication. The longword-integer-multiplier argument is the
    address of a signed longword integer containing the multiplier.

 longword-integer-multiplicand

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

    Multiplicand used by LIB$EMUL in the extended-precision
    multiplication. The longword-integer-multiplicand argument is the
    address of a signed longword integer containing the multiplicand.

 addend

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

    Addend used by LIB$EMUL in the extended-precision multiplication.
    The addend argument is the address of a signed longword integer
    containing the addend.

 product

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       write only
    mechanism:    by reference

    Product of the extended-precision multiplication. The product
    argument is the address of a signed quadword integer into which
    LIB$EMUL writes the product.

2.60  –  LIB$ENABLE_CTRL

    The Enable CLI Interception of Control Characters routine
    requests the calling process's command language interpreter
    (CLI) to resume interception of the selected control characters
    when they are typed during an interactive terminal session.
    LIB$ENABLE_CTRL provides the same function as the DCL command
    SET CONTROL.

    Format

      LIB$ENABLE_CTRL  enable-mask [,old-mask]

2.60.1  –  Returns

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

2.60.2  –  Arguments

 enable-mask

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

    Bit mask indicating for which control characters LIB$ENABLE_
    CTRL is to enable interception. The enable-mask argument is the
    address of an unsigned longword containing this bit mask. Each
    of the 32 bits corresponds to one of the 32 possible control
    characters. If a bit is set, the corresponding control character
    is intercepted by the CLI. Currently, only bits 20 and 25,
    corresponding to Ctrl/T and Ctrl/Y, are recognized.

    The following mask is defined in symbol libraries supplied by VSI
    to specify the value of enable-mask:

    Symbol          Hex Value     Function

    LIB$M_CLI_      %X'00100000'  Enables Ctrl/T
    CTRLT
    LIB$M_CLI_      %X'02000000'  Enables Ctrl/Y
    CTRLY

    If a set bit does not correspond to a character that the CLI can
    intercept, an error is returned.

 old-mask

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

    Previous bit mask. The old-mask argument is the address of an
    unsigned longword containing the old bit mask. The old bit mask
    is of the same form as enable-mask.

2.61  –  LIB$ESTABLISH

    The Establish a Condition Handler routine moves the address of
    a condition handling routine (which can be a user-written or a
    library routine) to longword 0 of the stack frame of the caller
    of LIB$ESTABLISH.

    This routine is not available to native OpenVMS Alpha and I64
    programs but is recognized and handled appropriately by most VSI
    high-level language compilers.

    Format

      LIB$ESTABLISH  new-handler

2.61.1  –  Returns

    OpenVMS usage:routine
    type:         procedure value
    access:       write only
    mechanism:    by reference

    Previous contents of SF$A_HANDLER (longword 0) of the caller's
    stack frame; zero if no handler existed.

2.61.2  –  Argument

 new-handler

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by value

    Routine to be set up as the condition handler. The new-handler
    argument is the address of the procedure value to this routine.

2.62  –  LIB$EXPAND_NODENAME

    The Expand a Node Name to Its Full Name Equivalent routine
    expands a node name to its full name equivalent.

    Format

      LIB$EXPAND_NODENAME  nodename, fullname [,resultant-length]

2.62.1  –  Returns

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

2.62.2  –  Arguments

 nodename

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

    Node name to be expanded. The nodename argument contains the
    address of a descriptor pointing to this node-name string.

    The error LIB$_INVARG is returned if nodename contains an invalid
    node name, points to a null string, or contains more than 1024
    characters. The error LIB$_INVSTRDES is returned if nodename is
    an invalid descriptor.

 fullname

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

    Expanded node name. The fullname argument contains the address
    of a descriptor pointing to the expanded node-name string.
    LIB$EXPAND_NODENAME writes the expanded node-name string into
    the buffer pointed to by the fullname descriptor.

    The error LIB$_INVSTRDES is returned if fullname is an invalid
    descriptor.

    The length field of the fullname descriptor is not updated unless
    fullname is a dynamic descriptor with a length less than the
    resulting expanded full name. Refer to the OpenVMS RTL String
    Manipulation (STR$) Manual for dynamic string descriptor usage.

    The fullname argument contains an unusable result when
    LIB$EXPAND_NODENAME returns in error.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the expanded node name. The resultant-length argument
    is the address of an unsigned word that contains this length in
    bytes.

    The resultant-length argument contains an unusable result when
    LIB$EXPAND_NODENAME returns in error.

2.63  –  LIB$EXTV

    The Extract a Field and Sign-Extend routine returns a sign-
    extended longword field that has been extracted from the
    specified variable bit field. LIB$EXTV makes the VAX EXTV
    instruction available as a callable routine.

    Format

      LIB$EXTV  position ,size ,base-address

2.63.1  –  Returns

    OpenVMS usage:longword_signed
    type:         longword integer (signed)
    access:       write only
    mechanism:    by value

    Field extracted by LIB$EXTV, sign-extended to a longword.

2.63.2  –  Arguments

 position

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

    Position (relative to the base address) of the first bit in
    the field that LIB$EXTV extracts. The position argument is the
    address of a signed longword integer containing the position.

 size

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Size of the bit field LIB$EXTV extracts. The size argument is the
    address of an unsigned byte containing the size. The maximum size
    is 32 bits.

 base-address

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

    Base address of the bit field LIB$EXTV extracts from the
    specified variable bit field. The base-address argument is an
    unsigned longword containing the base address.

2.64  –  LIB$EXTZV

    The Extract a Zero-Extended Field routine returns a longword
    zero-extended field that has been extracted from the specified
    variable bit field. LIB$EXTZV makes the VAX EXTZV instruction
    available as a callable routine.

    Format

      LIB$EXTZV  position ,size ,base-address

2.64.1  –  Returns

    OpenVMS usage:longword_signed
    type:         longword integer (signed)
    access:       write only
    mechanism:    by value

    Field extracted by LIB$EXTZV, zero-extended to a longword.

2.64.2  –  Arguments

 position

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

    Position (relative to the base address) of the first bit in the
    field LIB$EXTZV extracts. The position argument is the address of
    a signed longword integer containing the position.

 size

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Size of the bit field LIB$EXTZV extracts. The size argument is
    the address of an unsigned byte containing the size. The maximum
    size is 32 bits.

 base-address

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

    Base address of the bit field LIB$EXTZV extracts. The base-
    address argument is an unsigned longword containing the base
    address.

2.65  –  LIB$FFx

    The Find First Clear or Set Bit routines search the field
    specified by the start position, size, and base for the first
    clear or set bit. LIB$FFC and LIB$FFS make the VAX FFC and VAX
    FFS instructions available as callable routines.

    Format

      LIB$FFC  position ,size ,base ,find-position

      LIB$FFS  position ,size ,base ,find-position

2.65.1  –  Returns

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

2.65.2  –  Arguments

 position

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

    Starting position, relative to the base address, of the bit field
    to be searched by LIB$FFx. The position argument is the address
    of a signed longword integer containing the starting position.

 size

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Number of bits to be searched by LIB$FFx. The size argument is
    the address of an unsigned byte containing the size of the bit
    field to be searched. The maximum size is 32 bits.

 base

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

    The base argument is the address of the bit field that LIB$FFx
    searches.

 find-position

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

    Bit position of the first bit in the specified state (clear or
    set), relative to the base address. The find-position argument
    is the address of a signed longword integer into which LIB$FFC
    writes the position of the first clear bit and into which LIB$FFS
    writes the position of the first set bit.

2.66  –  LIB$FID_TO_NAME

    The Convert Device and File ID to File Specification routine
    converts a disk device name and file identifier to a file
    specification.

    Format

      LIB$FID_TO_NAME  device-name ,file-id ,filespec

                       [,filespec-length] [,directory-id]

                       [,acp-status]

2.66.1  –  Returns

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

2.66.2  –  Arguments

 device-name

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

    Device name to be converted. The device-name argument is the
    address of a descriptor pointing to the device name. It must
    reference a disk device, and must contain 64 characters or less.
    LIB$FID_TO_NAME obtains device-name from the NAM$T_DVI field of
    an OpenVMS RMS name block.

 file-id

    OpenVMS usage:vector_word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference, array reference

    Specifies the file identifier. The file-id argument is the
    address of an array of three words containing the file
    identification. LIB$FID_TO_NAME obtains file-id from the NAM$W_
    FID field of an OpenVMS RMS name block. The $FIDDEF macro defines
    the structure of file-id.

 filespec

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

    Receives the file specification. The filespec argument is the
    address of a descriptor pointing to the file specification
    string. As of OpenVMS Version 7.2, the maximum file specification
    string that can be returned is 4095 bytes on Alpha and I64
    systems, and 510 bytes on VAX systems. On versions prior to
    Version 7.2, the maximum is 510 bytes on both platforms.

 filespec-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the number of characters written into filespec,
    excluding padding in the case of a fixed-length string. The
    optional filespec-length argument is the address of an unsigned
    word containing the number of characters.

    If the output string is truncated to the number of characters
    specified in filespec, then filespec-length is set to that
    truncated size. Therefore, you can always use filespec-length
    to access a valid substring of filespec.

 directory-id

    OpenVMS usage:vector_word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference, array reference

    Specifies a directory file identifier. The directory-id argument
    is the address of an array of three words containing the
    directory file identifier. LIB$FID_TO_NAME obtains this array
    from the NAM$W_DID field of an OpenVMS RMS name block. The
    $FIDDEF macro defines the structure of directory-id.

    This parameter is relevant only for a structure level-1 disk
    on OpenVMS VAX systems. This parameter is ignored on OpenVMS
    Alpha and I64 systems because level-1 disks are not supported on
    OpenVMS Alpha and I64 systems.

 acp-status

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

    The status resulting from traversing the backward links. The
    optional acp-status argument is the address of an unsigned
    longword containing the status.

2.67  –  LIB$FILE_SCAN

    The File Scan routine searches an area, such as a directory, for
    all files matching the file specification given and transfers
    program execution to the specified user-written routine.
    Wildcards are acceptable. An action routine is called for each
    file and/or error found. LIB$FILE_SCAN allows the search sequence
    to continue even if an error occurs while processing a particular
    file.

    Format

      LIB$FILE_SCAN  fab ,user-success-procedure

                     ,user-error-procedure [,context]

2.67.1  –  Returns

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

2.67.2  –  Arguments

 fab

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

    File Access Block (FAB) referencing a valid NAM block or NAML
    block. The fab argument is the address of the FAB that contains
    the address and length of the file specification being searched
    for by LIB$FILE_SCAN. On Alpha and I64 systems, NAML blocks
    support the use of file specifications with a maximum length
    of NAML$C_MAXRSS. See the OpenVMS Record Management Services
    Reference Manual for information on NAML blocks.

 user-success-procedure

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

    User-supplied success routine that LIB$FILE_SCAN calls when
    a file is found. The success routine is invoked with the FAB
    address that was passed to LIB$FILE_SCAN. The user context may be
    pased to this routine using the FAB$L_CTX field in the FAB.

 user-error-procedure

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

    User-supplied error routine that LIB$FILE_SCAN calls when it
    encounters an error. The error routine is called with the FAB
    argument that was passed to LIB$FILE_SCAN.

 context

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

    Default file context used in processing file specifications for
    multiple input files. The context argument is the address of
    a longword, which must be initialized to zero by your program
    before the first call to LIB$FILE_SCAN. After the first call,
    LIB$FILE_SCAN maintains this longword. You must not change the
    value of context in subsequent calls to LIB$FILE_SCAN.

    Name blocks and file specification strings are allocated by
    LIB$FILE_SCAN, and context is used to retain their addresses
    so they may be deallocated later. If the context argument is not
    passed, unspecified portions of the file specification will be
    inherited from the previous file specification processed, rather
    than from multiple input file specifications.

2.68  –  LIB$FILE_SCAN_END

    The End-of-File Scan routine is called after each sequence of
    calls to LIB$FILE_SCAN. LIB$FILE_SCAN_END deallocates any saved
    OpenVMS RMS context and/or deallocates the virtual memory that
    had been allocated for holding the related file specification
    information.

    Format

      LIB$FILE_SCAN_END  [fab] [,context]

2.68.1  –  Returns

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

2.68.2  –  Arguments

 fab

    OpenVMS usage:fab
    type:         unspecified
    access:       modify
    mechanism:    by reference

    File access block (FAB) used with LIB$FILE_SCAN. The optional fab
    argument is the address of the FAB that contains the address and
    length of the file specification.

 context

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

    Temporary default context used in LIB$FILE_SCAN. The optional
    context argument is the address of a longword containing this
    temporary default context.

2.69  –  LIB$FIND_FILE

    The Find File routine is called with a file specification for
    which it searches. LIB$FIND_FILE returns one file specification
    for each call. The file specification may contain wildcards.

    Format

      LIB$FIND_FILE  filespec ,resultant-filespec ,context

                     [,default-filespec] [,related-filespec]

                     [,status-value] [,flags]

2.69.1  –  Returns

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

2.69.2  –  Arguments

 filespec

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

    File specification, which may contain wildcards, that LIB$FIND_
    FILE uses to search for the desired file. The filespec
    argument is the address of a descriptor pointing to the file
    specification. If running on Alpha or I64 and flag LIB$M_FIL_
    LONG_NAMES is set, the maximum length of a file specification
    is specified by NAML$C_MAXRSS, otherwise the maximum length of a
    file specification is 255 bytes.

    The file specification used may also contain a search list
    logical name. If present, the search list logical name elements
    can be used as accumulative to related file specifications, so
    that portions of file specifications not specified by the user
    are inherited from previous file specifications.

 resultant-filespec

    OpenVMS usage:char_string
    type:         character string
    access:       modify
    mechanism:    by descriptor

    Resultant file specification that LIB$FIND_FILE returns when
    it finds a file that matches the specification in the filespec
    argument. The resultant-filespec argument is the address of a
    descriptor pointing to the resultant file specification.

 context

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

    A longword integer variable into which the routine stores a
    context value for use by future calls to LIB$FIND_FILE or
    LIB$FIND_FILE_END. The context argument is an unsigned longword
    integer containing the address of the context. This variable
    must be set to zero before the first call to LIB$FIND_FILE. You
    can use the same context argument from one LIB$FIND_FILE call to
    another provided you have not called LIB$FIND_FILE_END for that
    context first. LIB$FIND_FILE uses this argument to retain the
    context when processing multiple input files. Portions of file
    specifications that the user does not specify may be inherited
    from the last files processed because the file contexts are
    retained in this argument. You must not change the value of
    context in subsequent calls to LIB$FIND_FILE.

 default-filespec

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

    Default file specification. The default-filespec argument
    is the address of a descriptor pointing to the default
    file specification. 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 containing the context of the last
    file processed. The related-filespec argument is the address of a
    descriptor pointing to the related file specification.

    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. For
    more information on related file specifications, see the OpenVMS
    Record Management Services Reference Manual.

 status-value

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

    RMS secondary status value from a failing RMS operation. The
    status-value argument is an unsigned longword containing the
    address of a longword-length buffer to receive the RMS secondary
    status value (usually returned in the file access block field,
    FAB$L_STV).

 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    LIB$M_FIL_NOWILD   If set, LIB$FIND_FILE returns an error if
                            a wildcard character is input.
    1    LIB$M_FIL_         If set, this performs temporary
         MULTIPLE           defaulting for multiple input files
                            and the related-filespec argument is
                            ignored. See description of context
                            in LIB$FILE_SCAN. Each time LIB$FIND_
                            FILE is called with a different file
                            specification, the specification from the
                            previous call is automatically used as a
                            related file specification. This allows
                            parsing of the elements of a search-
                            list logical name such as DISK2:[SMITH]
                            FIL1.TYP,FIL*2.TYP, and so on. Use of
                            this feature is required to get the
                            desired defaulting with search list
                            logical name. LIB$FIND_FILE_END must
                            be called between each command line in
                            interactive use or the defaults from the
                            previous command line affect the current
                            file specification.
    2    LIB$M_FIL_LONG_    (Alpha and I64 only) If set, LIB$FIND_
         NAMES              FILE can process file specifications with
                            a maximum length of NAML$C_MAXRSS. If
                            clear, LIB$FIND_FILE can process file
                            specifications with a maximum length of
                            255 (default).

2.70  –  LIB$FIND_FILE_END

    The End of Find File routine is called once after each sequence
    of calls to LIB$FIND_FILE. LIB$FIND_FILE_END deallocates any
    saved OpenVMS RMS context and deallocates the virtual memory used
    to hold the allocated context block.

    Format

      LIB$FIND_FILE_END  context

2.70.1  –  Returns

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

2.70.2  –  Argument

 context

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

    Zero or the address of a FAB/NAM buffer from a previous call to
    LIB$FIND_FILE. The context argument is the address of a longword
    that contains this context.

2.71  –  LIB$FIND_IMAGE_SYMBOL

    The Find Universal Symbol in Shareable Image File routine reads
    universal symbols from the shareable image file. This routine
    then dynamically activates a shareable image into the P0 address
    space of a process.

    Format

      LIB$FIND_IMAGE_SYMBOL  filename ,symbol ,symbol-value

                             [,image-name] [,flags]

2.71.1  –  Returns

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

2.71.2  –  Arguments

 filename

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

    Name of the file for which LIB$FIND_IMAGE_SYMBOL is searching.
    The filename argument is the address of a descriptor pointing to
    this file name string. This argument may contain only the file
    name. File type cannot be indicated. If any file specification
    punctuation characters (:, [, <, ;, .) are present, the error
    SS$_IVLOGNAM is returned.

    You can specify a file specification for the image name with the
    optional image-name argument. If you do not specify image-name,
    a default file specification of SYS$SHARE:.EXE is applied to the
    file name. If the file is not in SYS$SHARE:.EXE, a logical name
    must be used to direct this routine to locate the correct file.
    Only logical names defined in the system logical name table with
    the /EXEC attribute will be considered while the image activator
    is processing a request from an image that was installed with
    privileges. If the calling image was installed with privileges,
    the image being activated and any shareable images or message
    sections it references must be installed as a known image with
    the INSTALL utility. Running an image to which you have only
    Execute (not Read) access results in the same restrictions on
    logical names and shareable images as does running a privileged
    image.

    On VAX systems, the filename descriptor must be class D, S, or Z.

 symbol

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

    Symbol for which LIB$FIND_IMAGE_SYMBOL is searching in the
    filename file. The symbol argument is the address of a descriptor
    pointing to the symbol name string. The symbol name string can be
    input in uppercase, lowercase, or mixed case letters.

 symbol-value

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

    Symbol value that LIB$FIND_IMAGE_SYMBOL has located. The symbol-
    value argument is the address of a signed longword integer
    into which LIB$FIND_IMAGE_SYMBOL returns the symbol value. If
    the symbol is relocatable, the starting virtual address of the
    shareable image in memory is added to the symbol value.

 image-name

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

    Default file specification applied to the image name. The
    optional image-name argument is a string used as the RMS default
    file specification when parsing filename as the primary filename.
    If image-name is not supplied, then a default file specification
    of SYS$SHARE:.EXE is applied to the image name.

    On VAX systems, the image-name descriptor must be class D, S, or
    Z.

 flags

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

    Control flags. The flags argument is the address of a longword
    integer that contains the control flags.

    Bit    Value                   Description

    0      Reserved to VSI
    1      Reserved to VSI
    2      Reserved to VSI
    3      Reserved to VSI
    4      LIB$M_FIS_MIXEDCASE     Causes LIB$FIND_IMAGE_SYMBOL
                                   to look for the symbol without
                                   converting it to uppercase.

    This is an optional argument. If omitted, the default is 0. If
    omitted, or if LIB$M_FIS_MIXEDCASE (bit 4) is 0, LIB$FIND_IMAGE_
    SYMBOL converts the specified symbol to uppercase before it is
    used.

2.72  –  LIB$FIND_VM_ZONE

    The Return the Next Valid Zone Identifier routine returns the
    zone identifier of the next valid zone in the heap management
    32-bit database.

    Format

      LIB$FIND_VM_ZONE  context ,zone-id

2.72.1  –  Returns

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

2.72.2  –  Arguments

 context

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

    Context specifier. The context argument is the address of an
    unsigned longword used to keep the scan context for finding the
    next valid zone. The context argument must be 0 to initialize the
    scan and to start with the first returnable zone identifier.

 zone-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Zone identifier. The zone-id argument is the address of an
    unsigned longword that receives the zone identifier for the next
    zone.

2.73  –  LIB$FIND_VM_ZONE_64

    (Alpha and I64 only.) The Return the Next Valid Zone Identifier
    routine returns the zone identifier of the next valid zone in the
    heap management 64-bit database.

    Format

      LIB$FIND_VM_ZONE_64  context ,zone-id

2.73.1  –  Returns

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

2.73.2  –  Arguments

 context

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

    Context specifier. The context argument is the address of an
    unsigned quadword used to keep the scan context for finding the
    next valid zone. The context argument must be 0 to initialize the
    scan and to start with the first returnable zone identifier.

 zone-id

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Zone identifier. The zone-id argument is the address of an
    unsigned quadword that receives the zone identifier for the next
    zone.

2.74  –  LIB$FIT_NODENAME

    The Fit a Node Name Into an Output Field routine fits a node name
    into an output field. It attempts to compress the node name to
    fit the output field. If this fails, it trims the node name.

    Format

      LIB$FIT_NODENAME  nodename, output-buffer

                        [,output-width][,resultant-length]

2.74.1  –  Returns

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

2.74.2  –  Arguments

 nodename

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

    Node name to be fitted into the desired output field. The
    nodename argument contains the address of a descriptor pointing
    to this node-name string.

    The error LIB$_INVARG is returned if nodename contains an invalid
    node name, points to a null string, or contains more than 1024
    characters. The error LIB$_INVSTRDES is returned if nodename is
    an invalid descriptor.

 output-buffer

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

    The output buffer. The output-buffer argument contains the
    address of a descriptor pointing to the output buffer. LIB$FIT_
    NODENAME writes the final output node name into the buffer
    pointed to by output-buffer.

    The error LIB$_INVSTRDES is returned if output-buffer is an
    invalid descriptor.

    The length field of the output-buffer descriptor is not updated
    unless output-buffer is a dynamic descriptor with a length less
    than the resulting fitted node name. Refer to the OpenVMS RTL
    String Manipulation (STR$) Manual for dynamic string descriptor
    usage.

    The output-buffer argument contains an unusable result when
    LIB$FIT_NODENAME returns in error.

 output-width

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Field width desired for the fit operation. The output-width
    argument is the address of an unsigned word that contains this
    field width in bytes.

    If output-width is omitted, the current length of output-buffer
    is used. If output-buffer is not a fixed-length string, specify
    output-width to ensure that the desired width is used.

    If the lengths of both output-buffer and output-width are
    specified, the length in output-width is used. In this case,
    if the current length of output-buffer is smaller than the length
    of output-width, the output node name is truncated at the end,
    and the alternate successful status LIB$_STRTRU is returned.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the output node name. The resultant-length argument
    is the address of an unsigned word that contains this length in
    bytes.

    The resultant-length argument contains an unusable result when
    LIB$FIT_NODENAME returns in error.

2.75  –  LIB$FIXUP_FLT

    The Fix Floating Reserved Operand routine finds the reserved
    operand of any F-floating, D-floating, G-floating, or H-floating
    instruction (with some exceptions) after a reserved operand fault
    has been signaled. LIB$FIXUP_FLT changes the reserved operand
    from -0.0 to the value of the  new-operand argument, if present;
    or to +0.0 if  new-operand is absent.

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

    Format

      LIB$FIXUP_FLT  signal-arguments ,mechanism-arguments

                     [,new-operand]

2.75.1  –  Returns

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

2.75.2  –  Arguments

 signal-arguments

    OpenVMS usage:vector_longword_unsigned
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Signal argument vector. The signal-arguments argument is the
    address of an array of unsigned longwords containing the signal
    argument vector.

 mechanism-arguments

    OpenVMS usage:vector_longword_unsigned
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Mechanism argument vector. The mechanism-arguments argument is
    the address of an array of unsigned longwords containing the
    mechanism argument vector.

 new-operand

    OpenVMS usage:floating-point
    type:         F_floating
    access:       read only
    mechanism:    by reference

    An F-floating value to replace the reserved operand. The
    new-operand argument is the address of an F-floating number
    containing the new operand. This is an optional argument. If
    omitted, the default value is +0.0.

2.76  –  LIB$FLT_UNDER

    The Floating-Point Underflow Detection routine enables or
    disables floating-point underflow detection for the calling
    routine activation. The previous setting is returned as a
    function value.

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

    Format

      LIB$FLT_UNDER  new-setting

2.76.1  –  Returns

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

    The old floating-point underflow enable setting (the previous
    contents of the SF$W_PSW[PSW$V_FU] in the caller's frame).

2.76.2  –  Argument

 new-setting

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

    New floating-point underflow enable setting. The new-setting
    argument is the address of an unsigned byte containing the
    new setting. Bit 0 set to 1 means enable; bit 0 set to 0 means
    disable.

2.77  –  LIB$FORMAT_DATE_TIME

    The Format Date and/or Time routine allows the user to select
    at run time a specific output language and format for a date or
    time, or both.

    Format

      LIB$FORMAT_DATE_TIME  date-string [,date] [,user-context]

                            [,date-length] [,flags]

2.77.1  –  Returns

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

2.77.2  –  Arguments

 date-string

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

    Receives the requested date or time, or both, that has been
    formatted for output according to the currently selected format
    and language. The date-string argument is the address of a
    descriptor pointing to this string.

 date

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    The date or time, or both, to be formatted for output. The date
    argument is the address of an unsigned quadword that contains
    the absolute date or time, or both to be formatted. If you omit
    this argument, or if you supply a zero passed by value, then the
    current system time is used. Note that the date argument must
    represent an absolute time, not a delta time.

 user-context

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

    User context that retains the translation context over multiple
    calls to this routine. The user-context argument is the address
    of an unsigned longword that contains this context. The initial
    value of the context variable must be zero. Thereafter, the user
    program must not write to the cell.

    The user-context parameter is optional. However, if a context
    cell is not passed, the routine LIB$FORMAT_DATE_TIME may abort
    if two threads of execution attempt to manipulate the context
    area concurrently. Therefore, when calling this routine in
    situations where reentrancy might occur, such as from AST level,
    VSI recommends that users specify a different context cell for
    each calling thread.

 date-length

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

    Number of bytes of text written to the  date-string argument.
    The date-length argument is the address of a signed longword that
    receives this string length. Note that date-length specifies the
    number of bytes of text, not the number of characters, written to
    date-string.

 flags

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

    Bit mask that allows the user to specify whether the date, time,
    or both are output. The flags argument is the address of an
    unsigned bit mask containing the specified values. Valid values
    are LIB$M_DATE_FIELDS and LIB$M_TIME_FIELDS.

    Default values are determined as follows:

    o  If the flags argument is omitted, LIB$FORMAT_DATE_TIME
       determines which fields to format according to the current
       definition of LIB$DT_FORMAT.

    o  If the flags argument is specified, LIB$FORMAT_DATE_TIME uses
       the flags value to determine which fields to format. That is,
       the flags argument can be used to override the definition of
       LIB$DT_FORMAT when specifying which fields should be formatted
       for output. If the field specified by flags was not assigned a
       format through the definition of LIB$DT_FORMAT, the standard
       OpenVMS format is used.

2.78  –  LIB$FORMAT_SOGW_PROT

    The Format Protection Mask routine translates a protection mask
    into a formatted string.

    Format

      LIB$FORMAT_SOGW_PROT  protection-mask, [access-names],

                            [ownership-names], [ownership-separator],

                            [list-separator], protection-string,

                            [protection-length]

2.78.1  –  Returns

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

2.78.2  –  Arguments

 protection-mask

    OpenVMS usage:protection
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    The address of a word that holds a 16-bit protection mask to be
    translated.

 access-names

    OpenVMS usage:access_names
    type:         array [0..31] of quadword string descriptor
    access:       read only
    mechanism:    by reference

    The address of the access name table for the associated object
    class. For example, it is the value returned in accnam by
    LIB$GET_ACCNAM. This parameter defaults to the access name table
    for the FILE object class.

 ownership-names

    OpenVMS usage:char_string
    type:         array [0..3] of quadword string descriptor
    access:       read only
    mechanism:    by reference

    The address of a vector of 4 quadword descriptors that points
    to the ownership name. The default value is the full ownership
    category names (System, Owner, Group, World).

 ownership-separator

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

    The address of a descriptor that points to the ownership
    separator string. The separator string is inserted after the
    ownership name to introduce a nonempty set of access names. By
    default, the value is ": " (the colon and space characters).

 list-separator

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

    The address of a descriptor that points to the list separator
    string. The list separator string is inserted between ownership-
    access type pairs. By default, the value is ", " (the comma and
    space characters).

 protection-string

    OpenVMS usage:char_string
    type:         character-coded text string
    access:        write only
    mechanism:    by descriptor

    The address of a character-string descriptor that receives the
    output of the routine call. The protection-string argument points
    to the formatted protection string at the end of a call. The
    protection string has the following components repeated for each
    of: System, Owner, Group, World:

    ownership-name[ownership-separator][access-types][list-separator]

    An example of a formatted protection string is

    System: RWED, Owner: RWED, Group: RW, World: R

 protection-length

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       write only
    mechanism:    by reference

    The address of a word that receives the length of the string
    returned in the protection-string argument.

2.79  –  LIB$FREE_DATE_TIME_CONTEXT

    The Free the Context Area Used When Formatting Dates and Times
    for Input or Output routine frees the virtual memory associated
    with the context area used by the date/time input and output
    formatting routines.

    Format

      LIB$FREE_DATE_TIME_CONTEXT  [user-context]

2.79.1  –  Returns

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

2.79.2  –  Argument

 user-context

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

    User context that retains the translation context over multiple
    calls to the date/time input and output formatting routines.
    The user-context argument is the address of an unsigned longword
    that contains this context. If the user-context argument was not
    specified in the call to LIB$FORMAT_DATE_TIME, LIB$CONVERT_DATE_
    STRING, or LIB$GET_MAXIMUM_DATE_LENGTH, then no argument should
    be supplied when calling this routine.

2.80  –  LIB$FREE_EF

    The Free Event Flag routine frees a local event flag previously
    allocated by LIB$GET_EF or by LIB$RESERVE_EF. LIB$FREE_EF is the
    complement of LIB$GET_EF.

    Format

      LIB$FREE_EF  event-flag-number

2.80.1  –  Returns

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

2.80.2  –  Argument

 event-flag-number

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

    Event flag number to be deallocated by LIB$FREE_EF. The event-
    flag-number argument is the address of a signed longword integer
    that contains the event flag number, which is the value allocated
    to the user by LIB$GET_EF or LIB$RESERVE_EF.

2.81  –  LIB$FREE_LUN

    The Free Logical Unit Number routine releases a logical unit
    number allocated by LIB$GET_LUN to the pool of available numbers.
    LIB$FREE_LUN is the complement of LIB$GET_LUN.

    Format

      LIB$FREE_LUN  logical-unit-number

2.81.1  –  Returns

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

2.81.2  –  Argument

 logical-unit-number

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

    Logical unit number to be deallocated. The logical-unit-number
    argument is the address of a signed longword integer that
    contains this logical unit number, which is the value previously
    returned by LIB$GET_LUN.

2.82  –  LIB$FREE_TIMER

    The Free Timer Storage routine frees the storage allocated by
    LIB$INIT_TIMER.

    Format

      LIB$FREE_TIMER  handle-address

2.82.1  –  Returns

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

2.82.2  –  Argument

 handle-address

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

    Pointer to a block of storage containing the value returned by
    a previous call to LIB$INIT_TIMER; this is the storage that
    LIB$FREE_TIMER deallocates. The handle-address argument is the
    address of an unsigned longword containing that value.

2.83  –  LIB$FREE_VM

    The Free Virtual Memory from Program Region routine deallocates
    an entire block of contiguous bytes that was allocated by a
    previous call to LIB$GET_VM. The arguments passed are the same
    as for LIB$GET_VM.

    Format

      LIB$FREE_VM  number-of-bytes ,base-address [,zone-id]

2.83.1  –  Returns

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

2.83.2  –  Arguments

 number-of-bytes

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

    Number of contiguous bytes to be deallocated by LIB$FREE_VM.
    The number-of-bytes argument is the address of a signed longword
    integer that contains this number. The value of number-of-bytes
    must be greater than zero.

    Byte counts are rounded in the same manner as in LIB$GET_VM.

                                   NOTE

       You may omit the number-of-bytes argument if you are using
       boundary tags (LIB$M_VM_BOUNDARY_TAGS).

 base-address

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

    Address of the first byte to be deallocated by LIB$FREE_VM.
    The base-address argument contains the address of an unsigned
    longword that is this address. The value of base-address must be
    the address of a block of memory that was allocated by a previous
    call to LIB$GET_VM.

 zone-id

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

    The address of a longword that contains a zone identifier created
    by a previous call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_
    ZONE.

    You must specify the same zone-id value as when you called
    LIB$GET_VM to allocate the block. An error status will be
    returned if you specify an incorrect zone-id. The zone-id
    argument is optional. If zone-id is omitted or if the longword
    contains the value 0, the 32-bit default zone is used.

2.84  –  LIB$FREE_VM_64

    (Alpha and I64 only.) The Free Virtual Memory from Program Region
    routine deallocates an entire block of contiguous bytes that
    was allocated by a previous call to LIB$GET_VM_64. The arguments
    passed are the same as for LIB$GET_VM_64.

    Format

      LIB$FREE_VM_64  number-of-bytes ,base-address [,zone-id]

2.84.1  –  Returns

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

2.84.2  –  Arguments

 number-of-bytes

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Number of contiguous bytes to be deallocated by LIB$FREE_VM_64.
    The number-of-bytes argument is the address of a signed quadword
    integer that contains this number. The value of number-of-bytes
    must be greater than zero.

    Byte counts are rounded in the same manner as in LIB$GET_VM_64.

                                   NOTE

       You may omit the number-of-bytes argument if you are using
       boundary tags (LIB$M_VM_BOUNDARY_TAGS).

 base-address

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Address of the first byte to be deallocated by LIB$FREE_VM_64.
    The base-address argument contains the address of an unsigned
    quadword that is this address. The value of base-address must be
    the address of a block of memory that was allocated by a previous
    call to LIB$GET_VM_64.

 zone-id

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    The address of a quadword that contains a zone identifier created
    by a previous call to LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_
    VM_ZONE_64.

    You must specify the same zone-id value as when you called
    LIB$GET_VM_64 to allocate the block. An error status will
    be returned if you specify an incorrect zone-id. The zone-id
    argument is optional. If zone-id is omitted or if the quadword
    contains the value 0, the 64-bit default zone is used.

2.85  –  LIB$FREE_VM_PAGE

    The Free Virtual Memory Page routine deallocates a block of
    contiguous pages on VAX systems or pagelets on Alpha and I64
    systems that were allocated by previous calls to LIB$GET_VM_PAGE.

    Format

      LIB$FREE_VM_PAGE  number-of-pages ,base-address

2.85.1  –  Returns

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

2.85.2  –  Arguments

 number-of-pages

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

    Number of pages on VAX systems or pagelets on Alpha and I64
    systems. The number-of-pages argument is the address of a
    longword integer that specifies the number of contiguous pages
    on VAX systems or pagelets on Alpha and I64 systems to be
    deallocated. The value of number-of-pages must be greater than
    zero.

 base-address

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

    Block address. The base-address argument is the address of a
    longword that contains the address of the first byte of the first
    VAX page or Alpha or I64 pagelet to be deallocated.

2.86  –  LIB$FREE_VM_PAGE_64

    (Alpha and I64 only.) The Free Virtual Memory Page routine
    deallocates a block of contiguous Alpha or I64 pagelets that
    was allocated by previous calls to LIB$GET_VM_PAGE_64.

    Format

      LIB$FREE_VM_PAGE_64  number-of-pages ,base-address

2.86.1  –  Returns

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

2.86.2  –  Arguments

 number-of-pages

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Number of Alpha or I64 pagelets. The address of a quadword
    integer that specifies the number of contiguous Alpha or I64
    pagelets to be deallocated. The value of number-of-pages must be
    greater than zero.

 base-address

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Block address. The base-address argument is the address of a
    quadword that contains the address of the first byte of the first
    Alpha or I64 pagelet to be deallocated.

2.87  –  LIB$GETDVI

    The Get Device/Volume Information routine provides a simplified
    interface to the $GETDVI system service. It returns information
    about the primary and secondary device characteristics of an I/O
    device. The calling process need not have a channel assigned to
    the device about which it wants information.

    Format

      LIB$GETDVI  item-code [,channel] [,device-name]

                  [,longword-integer-value] [,resultant-string]

                  [,resultant-length] [,pathname]

2.87.1  –  Returns

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

2.87.2  –  Arguments

 item-code

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

    Code specifying the item of information you are requesting. The
    item-code argument is the address of a signed longword containing
    the item code. All valid $GETDVI item codes whose names begin
    with DVI$_ are accepted.

 channel

    OpenVMS usage:channel
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    OpenVMS I/O channel assigned to the device for which LIB$GETDVI
    returns information. The channel argument is the address of an
    unsigned word containing the channel specification. If channel is
    not specified, device-name is used instead. You must specify
    either channel or device-name, but not both. If neither is
    specified, the error status SS$_IVDEVNAM is returned.

 device-name

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

    Name of the device for which LIB$GETDVI returns information.
    The device-name argument is the address of a descriptor pointing
    to the device name string. If this string contains a colon, the
    colon and the characters that follow it are ignored.

    The device-name may be either a physical device name or a logical
    name. If the first character in the string is an underscore
    character (_),  the name is considered a physical device name.
    Otherwise, the name is considered a logical name, and logical
    name translation is performed until either a physical device name
    is found or the system default number of translations has been
    performed.

    If device-name is not specified, channel is used instead. You
    must specify either channel or device-name, but not both. If
    neither is specified, the error status SS$_IVDEVNAM is returned.
    The device name must not be longer than 255 characters.

 longword-integer-value

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

    Numeric value of the information requested. The longword-integer-
    value argument is the address of a signed longword containing the
    numeric value. If an item is listed as only returning a string
    value, this argument is ignored.

 resultant-string

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

    String representation of the information requested. The
    resultant-string argument is the address of a descriptor pointing
    to this information. If resultant-string is not specified and if
    the value returned has only a string representation, the error
    status LIB$_INVARG is returned.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of significant characters written to resultant-string by
    LIB$GETDVI. The resultant-length argument is the address of an
    unsigned word containing this length.

 pathname

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

    (I64 and Alpha only) The name of the path about which $GETDVI
    is to return information. The pathname argument is the address
    of a character string descriptor pointing to this name string.
    The path name may be used with either the channel or device-name
    arguments.

    Check the definitions of the item codes to see if the pathname
    argument is used. In general, item codes that return information
    that may vary by path will make use of the pathname argument.
    The paths for a multipath device can be seen with the SHOW DEVICE
    /FULL command, the SYS$DEVICE_PATH_SCAN system service, or the
    F$MULTIPATH DCL lexical function.

    If the pathname argument is used, it will be validated against
    the existing paths for the device specified. If the path does
    not exist, the error SS$_NOSUCHPATH will be returned, even if the
    item codes(s) used do not make use of the pathname argument.

2.88  –  LIB$GETJPI

    The Get Job/Process Information routine provides a simplified
    interface to the $GETJPI system service. It provides accounting,
    status, and identification information about a specified process.

    LIB$GETJPI obtains only one item of information in a single call.

    Format

      LIB$GETJPI  item-code [,process-id] [,process-name]

                  [,resultant-value] [,resultant-string]

                  [,resultant-length]

2.88.1  –  Returns

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

2.88.2  –  Arguments

 item-code

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

    Item identifier code specifying the item of information you are
    requesting. The item-code argument is the address of a signed
    longword containing the item code. You may request only one item
    in each call to LIB$GETJPI.

    LIB$GETJPI accepts all $GETJPI item codes. These names begin
    with JPI$_ and are defined in symbol libraries in module $JPIDEF
    supplied by VSI.

 process-id

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

    Process identifier of the process for which you are requesting
    information. The process-id argument is the address of an
    unsigned longword containing the process identifier. If you do
    not specify process-id, process-name is used.

    The process-id is updated to contain the process identifier
    actually used, which may be different from what you originally
    requested if you specified process-name or used wildcard process
    searching.

 process-name

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

    A 1- to 15-character string specifying the name of the process
    for which you are requesting information. The process-name
    argument is the address of a descriptor pointing to the process
    name string. The name must correspond exactly to the name of the
    process for which you are requesting information; LIB$GETJPI does
    not allow trailing blanks or abbreviations.

    If you do not specify process-name, process-id is used. If you
    specify neither process-name nor process-id, the caller's process
    is used. Also, if you do not specify process-name and you specify
    zero for process-id, the caller's process is used. In this way,
    you can fetch the item you want and the caller's PID in a single
    call to LIB$GETJPI.

 resultant-value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    Numeric value of the information you request. The resultant-value
    argument is the address of a longword or quadword into which
    LIB$GETJPI writes the numeric value of this information.

 resultant-string

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

    String representation of the information you request. The
    resultant-string argument is the address of the descriptor
    for a character string into which LIB$GETJPI writes the string
    representation.

    If you do not include resultant-string, but the item you request
    has only a string representation, the error status LIB$_INVARG is
    returned.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of significant characters written to resultant-string by
    LIB$GETJPI. The resultant-length argument is the address of an
    unsigned word integer into which LIB$GETJPI writes the number of
    characters.

2.89  –  LIB$GETQUI

    The Get Queue Information routine provides a simplified interface
    to the $GETQUI system service. It provides queue, job, file,
    characteristic, and form information about a specified process.

    LIB$GETQUI obtains only one item of information in a single call.

    Format

      LIB$GETQUI  function-code [,item-code] [,search-number]

                  [,search-name] [,search-flags] [,resultant-value]

                  [,resultant-string] [,resultant-length]

2.89.1  –  Returns

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

2.89.2  –  Arguments

 function-code

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

    Function code specifying the function that LIB$GETQUI is to
    perform. The function-code argument is the address of a signed
    longword containing the function code.

    LIB$GETQUI accepts all $GETQUI function codes. These names begin
    with QUI$_ and are defined in symbol libraries in module $QUIDEF
    supplied by VSI.

 item-code

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

    Item identifier code specifying the item of information you are
    requesting. The item-code argument is the address of a signed
    longword containing the item code. You may request only one item
    in each call to LIB$GETQUI.

    LIB$GETQUI accepts all $GETQUI item codes. These names begin
    with QUI$_ and are defined in symbol libraries in module $QUIDEF
    supplied by VSI.

 search-number

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

    Numeric value used to process your request. The search-number
    argument is the address of a signed longword integer containing
    the number needed to process your request. The search-number
    argument corresponds directly to QUI$_SEARCH_NUMBER as described
    by the $GETQUI system service.

 search-name

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

    Character string used to process your request. The search-name
    argument is the address of a string descriptor that provides the
    name needed to process your request. The search-name argument
    corresponds directly to QUI$_SEARCH_NAME as described by the
    $GETQUI system service.

 search-flags

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

    Optional bit mask indicating request to be performed. The search-
    flags argument is the address of an unsigned longword integer
    containing the bit mask. The search-flags argument directly
    corresponds to $QUI_SEARCH_FLAGS as described by the $GETQUI
    system service.

 resultant-value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    Numeric value of the information you requested. The resultant-
    value argument is the address of a longword, quadword or
    octaword into which LIB$GETQUI writes the numeric value of this
    information.

    If the item you requested returns only a string value, this
    argument is ignored.

 resultant-string

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

    String representation of the information you requested. The
    resultant-string argument is the address of the descriptor
    for a character string into which LIB$GETQUI writes the string
    representation.

    If you do not include resultant-string, but the item you request
    has only a string representation, the error status LIB$_INVARG is
    returned.

 resultant-length

    OpenVMS usage:word_signed
    type:         word integer (signed)
    access:       write only
    mechanism:    by reference

    Number of significant characters written to resultant-string by
    LIB$GETQUI. The resultant-length argument is the address of a
    signed word integer into which LIB$GETQUI writes the number of
    characters.

2.90  –  LIB$GETSYI

    The Get Systemwide Information routine provides a simplified
    interface to the $GETSYI system service. The $GETSYI system
    service obtains status and identification information about the
    system. LIB$GETSYI returns only one item of information in a
    single call.

    Format

      LIB$GETSYI  item-code [,resultant-value] [,resultant-string]

                  [,resultant-length] [,cluster-system-id]

                  [,node-name]

2.90.1  –  Returns

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

2.90.2  –  Arguments

 item-code

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

    Item code specifying the desired item of information. The item-
    code argument is the address of a signed longword containing this
    item code. All valid $GETSYI item codes are accepted.

 resultant-value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    Numeric value returned by LIB$GETSYI. The resultant-value
    argument is the address of a longword or quadword containing this
    value. If an item is listed as returning only a string value,
    this argument is ignored.

 resultant-string

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

    Information returned by LIB$GETSYI. The resultant-string argument
    is the address of a descriptor pointing to the character string
    that will receive this information. If resultant-string is
    not specified and if the returned value has only a string
    representation, the error status LIB$_INVARG is returned.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of significant characters written to resultant-string, not
    including blank padding or truncated characters. The resultant-
    length argument is the address of an unsigned word into which
    LIB$GETSYI returns this number.

 cluster-system-id

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

    Cluster system identification (CSID) of the node for which
    information is to be returned. The cluster-system-id argument
    is the address of this CSID. If cluster-system-id is specified
    and is nonzero, node-name is not used. If cluster-system-id is
    specified as zero, LIB$GETSYI uses node-name and writes into the
    cluster-system-id argument the CSID corresponding to the node
    identified by node-name.

    The cluster-system-id of an OpenVMS node is assigned by the
    cluster-connection software and may be obtained by the DCL
    command SHOW CLUSTER. The value of the cluster-system-id for
    an OpenVMS node is not permanent; a new value is assigned to an
    OpenVMS node whenever it joins or rejoins the OpenVMS Cluster.

    If cluster-system-id is specified as -1, LIB$GETSYI assumes a
    wildcard operation and returns the requested information for each
    OpenVMS node in the cluster, one node per call.

    If cluster-system-id is not specified, node-name is used.

 node-name

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

    Name of the node for which information is to be returned. The
    node-name argument is the address of a descriptor pointing to
    the node name string. If cluster-system-id is not specified or
    is specified as zero, node-name is used. If neither node-name nor
    cluster-system-id is specified, the caller's node is used. See
    the cluster-system-id argument for more information.

    The node name string must contain from 1 to 15 characters and
    must correspond exactly to the OpenVMS node name; no trailing
    blanks nor abbreviations are permitted.

2.91  –  LIB$GET_ACCNAM

    The Get Access Name Table for Protected Object Class (by Name)
    routine is a simplified interface to the $GET_SECURITY system
    service, and returns a pointer to the access name table for a
    protected object class that is specified by name.

    Format

      LIB$GET_ACCNAM  [clsnam] , [objnam] ,accnam

2.91.1  –  Returns

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

2.91.2  –  Arguments

 clsnam

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

    The address of a character-string descriptor pointing to the
    name of a protected object class. This argument is optional and
    defaults to FILE.

 objnam

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

    The address of a character-string descriptor pointing to the
    name of a protected object. This argument is optional. If it is
    omitted, the access name table returned is that used for objects
    of the class specified by the clsnam argument.

 accnam

    OpenVMS usage:access_names
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    The address of a longword into which this routine writes the
    address of the access name table.

2.92  –  LIB$GET_ACCNAM_BY_CONTEXT

    The Get Access Name Table for Protected Object Class (by Context)
    routine is a simplified interface to the $GET_SECURITY system
    service, and returns a pointer to the access name table for a
    protected object class that is specified by a context longword
    returned from $GET_SECURITY or $SET_SECURITY.

    Format

      LIB$GET_ACCNAM_BY_CONTEXT  contxt ,accnam

2.92.1  –  Returns

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

2.92.2  –  Arguments

 contxt

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

    The address of a nonzero longword context value returned by $GET_
    SECURITY or $SET_SECURITY.

 accnam

    OpenVMS usage:access_names
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    The address of a longword into which this routine writes the
    address of the access name table.

2.93  –  LIB$GET_COMMAND

    The Get Line from SYS$COMMAND routine gets one record of ASCII
    text from the current controlling input device, specified by the
    logical name SYS$COMMAND.

    Format

      LIB$GET_COMMAND  resultant-string [,prompt-string]

                       [,resultant-length]

2.93.1  –  Returns

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

2.93.2  –  Arguments

 resultant-string

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

    String that LIB$GET_COMMAND gets from SYS$COMMAND. The resultant-
    string argument is the address of a descriptor pointing to this
    string.

 prompt-string

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

    Prompt message that LIB$GET_COMMAND displays on the controlling
    terminal. The prompt-string argument is the address of a
    descriptor pointing to the prompt. Any string can be a valid
    prompt. By convention however, a prompt string consists of text
    followed by a colon (:),  a space, and no carriage-return/line-
    feed combination. The maximum size of the prompt message is 255
    characters. If the controlling input device is not a terminal,
    this argument is ignored.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of bytes written into resultant-string by LIB$GET_
    COMMAND, not counting padding in the case of a fixed string.
    The resultant-length argument is the address of an unsigned word
    containing this length. If the input string is truncated to the
    size specified in the resultant-string descriptor, resultant-
    length is set to this size. Therefore, resultant-length can
    always be used by the calling program to access a valid substring
    of resultant-string.

2.94  –  LIB$GET_COMMON

    The Get String from Common routine copies a string in the common
    area to the destination string. (The common area is an area of
    storage that remains defined across multiple image activations in
    a process.) The string length is taken from the first longword of
    the common area.

    Format

      LIB$GET_COMMON  resultant-string [,resultant-length]

2.94.1  –  Returns

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

2.94.2  –  Arguments

 resultant-string

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

    Destination string into which LIB$GET_COMMON writes the string
    copied from the common area. The resultant-string argument is the
    address of a descriptor pointing to the destination string.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of characters written into resultant-string by LIB$GET_
    COMMON, not counting padding in the case of a fixed-length
    string. The resultant-length argument is the address of an
    unsigned word integer containing the number of characters copied.
    If the input string is truncated to the size specified in the
    resultant-string descriptor, resultant-length is set to this
    size. Therefore, resultant-length can always be used by the
    calling program to access a valid substring of resultant-string.

2.95  –  LIB$GET_CURR_INVO_CONTEXT

    (Alpha and I64 only.) The Get Current Invocation Context routine
    gets the current invocation context of any active procedure.

    A thread can obtain the invocation context of a current procedure
    using the following function format:

    Format

      LIB$GET_CURR_INVO_CONTEXT   invo_context

2.95.1  –  Returns

    None.

2.95.2  –  Argument

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       write only
    mechanism:    by reference

    Address of an invocation context block into which the procedure
    context of the caller will be written.

2.96  –  LIB$GET_DATE_FORMAT

    The Get the User's Date Input Format routine returns information
    about the user's choice of a date/time input format.

    Format

      LIB$GET_DATE_FORMAT  format-string [,user-context]

2.96.1  –  Returns

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

2.96.2  –  Arguments

 format-string

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

    Receives the translation of LIB$DT_INPUT_FORMAT. The format-
    string argument is the address of a descriptor pointing to this
    format string.

 user-context

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

    Context variable that retains the translation context over
    multiple calls to this routine. The user-context argument is the
    address of an unsigned longword that contains this context. The
    initial value of the context variable must be zero. Thereafter,
    the user program must not write to the cell.

    The user-context argument is optional. However, if a context cell
    is not passed, LIB$GET_DATE_FORMAT may abort if two threads of
    execution attempt to manipulate the context area concurrently.
    Therefore, when calling this routine in situations where
    reentrancy might occur, such as from AST level, VSI recommends
    that users specify a different context cell for each calling
    thread.

2.97  –  LIB$GET_EF

    The Get Event Flag routine allocates one local event flag from
    a processwide pool and returns the number of the allocated flag
    to the caller. If no flags are available, LIB$GET_EF returns an
    error as its function value.

    Format

      LIB$GET_EF  event-flag-number

2.97.1  –  Returns

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

2.97.2  –  Argument

 event-flag-number

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Number of the local event flag that LIB$GET_EF allocated, or -
    1 if no local event flag was available. The event-flag-number
    argument is the address of a signed longword integer into which
    LIB$GET_EF writes the number of the local event flag that it
    allocates.

2.98  –  LIB$GET_FOREIGN

    The Get Foreign Command Line routine requests the calling image's
    command language interpreter (CLI) to return the contents of the
    "foreign command" line that activated the current image.

    Format

      LIB$GET_FOREIGN  resultant-string [,prompt-string]

                       [,resultant-length] [,flags]

2.98.1  –  Returns

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

2.98.2  –  Arguments

 resultant-string

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

    String that LIB$GET_FOREIGN uses to receive the foreign
    command line. The resultant-string argument is the address of
    a descriptor pointing to this string. If the foreign command
    text returned was obtained by a prompt to SYS$INPUT (see the
    description of flags), the text is translated to uppercase so as
    to be more consistent with text returned from the CLI.

 prompt-string

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

    Optional user-supplied prompt for text that LIB$GET_FOREIGN uses
    if no command-line text is available. The prompt-string argument
    is the address of a descriptor pointing to the user prompt.
    If omitted, no prompting is performed. It is recommended that
    prompt-string be specified. If prompt-string is omitted and if
    no command-line text is available, a zero-length string will be
    returned.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of bytes written into resultant-string by LIB$GET_FOREIGN,
    not counting padding in the case of a fixed-length resultant-
    string. The resultant-length argument is the address of an
    unsigned word into which LIB$GET_FOREIGN writes the number of
    bytes.

 flags

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

    Value that LIB$GET_FOREIGN uses to control whether or not
    prompting is to be performed. The flags argument is the address
    of an unsigned longword integer containing this value. If the low
    bit of flags is zero, or if flags is omitted, prompting is done
    only if the CLI does not return a command line. If the low bit is
    1, prompting is done unconditionally. If specified, flags is set
    to 1 before returning to the caller.

    The primary use of flags is to allow a utility program to be
    invoked once with subcommand text on the command line, and then
    to repeatedly prompt for further subcommands from SYS$INPUT. This
    is accomplished by calling LIB$GET_FOREIGN repeatedly, specifying
    in the call a prompt-string string and a flags variable that
    is initialized to zero at the beginning of the program. The
    first call gets the subcommand text from the command line, after
    which flags will be set to 1, causing further subcommands to be
    requested through prompts to SYS$INPUT.

2.99  –  LIB$GET_FULLNAME_OFFSET

    The Get the Offset to the Starting Position of the Most
    Significant Part of a Full Name routine returns the offset to
    the starting position of the most significant part of a full
    name. The most significant part of a full name is determined by
    the underlying network services.

    Format

      LIB$GET_FULLNAME_OFFSET  fullname, offset

2.99.1  –  Returns

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

2.99.2  –  Arguments

 fullname

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

    Full name. The fullname argument contains the address of the
    descriptor pointing to this full name string.

    The error LIB$_INVARG is returned if fullname contains an invalid
    full name, points to a null string, or contains more than 1024
    characters. The error LIB$_INVSTRDES is returned if fullname is
    an invalid descriptor.

 offset

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    The offset in bytes of the starting position of the most
    significant part of fullname. The offset argument is the address
    of an unsigned word that contains this offset.

    The offset argument contains an unusable result when LIB$GET_
    FULLNAME_OFFSET returns in error.

2.100  –  LIB$GET_HOSTNAME

    The Get Host Node Name routine returns the host node name of the
    local system.

    Format

      LIB$GET_HOSTNAME  hostname [,resultant-length] [,flags]

2.100.1  –  Returns

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

2.100.2  –  Arguments

 hostname

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

    The host node name. The hostname argument contains the address
    of a descriptor pointing to the host node name. LIB$GET_HOSTNAME
    writes the host node-name string into the buffer pointed to by
    the hostname descriptor.

    The error LIB$_INVSTRDES is returned if hostname is an invalid
    descriptor.

    The length field of the hostname descriptor is not updated unless
    hostname is a dynamic descriptor with a length less than the
    host node name to be returned. Refer to the OpenVMS RTL String
    Manipulation (STR$) Manual for dynamic string descriptor usage.

    The hostname argument contains an unusable result when LIB$GET_
    HOSTNAME returns in error.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the host node name. The resultant-length argument is
    the address of an unsigned word that contains this length in
    bytes.

    The resultant-length argument contains an unusable result when
    LIB$GET_HOSTNAME returns in error.

 flags

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

    The value LIB$GET_HOSTNAME uses to control the form of the host
    node name that it returns in the output descriptor hostname. If
    flags is equal to 0, or if flags is omitted, the host node name
    returned is in the network usable form. If flags is equal to 1,
    the host node name returned is in the parsable form.

    Unused bits in flags must be 0. Nonzero unused bits result in the
    error condition LIB$_INVARG.

2.101  –  LIB$GET_INPUT

    The Get Line from SYS$INPUT routine gets one record of ASCII
    text from the current controlling input device, specified by
    SYS$INPUT.

    Format

      LIB$GET_INPUT  resultant-string [,prompt-string]

                     [,resultant-length]

2.101.1  –  Returns

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

2.101.2  –  Arguments

 resultant-string

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

    String that LIB$GET_INPUT gets from the input device. The
    resultant-string argument is the address of a descriptor pointing
    to the character string into which LIB$GET_INPUT writes the text
    received from the current input device.

 prompt-string

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

    Prompt message that is displayed on the controlling terminal. The
    prompt-string argument is the address of a descriptor containing
    the prompt. Any string can be a valid prompt. By convention
    however, a prompt consists of text followed by a colon (:),  a
    space, and no carriage-return/line-feed combination. The maximum
    size of the prompt message is 255 characters. If the controlling
    input device is not a terminal, this argument is ignored.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of bytes written into resultant-string by LIB$GET_
    INPUT, not counting padding in the case of a fixed string. The
    resultant-length argument is the address of an unsigned word
    containing this number. If the input string is truncated to the
    size specified in the resultant-string descriptor, resultant-
    length is set to this size. Therefore, resultant-length can
    always be used by the calling program to access a valid substring
    of resultant-string.

2.102  –  LIB$GET_INVO_CONTEXT

    (Alpha and I64 only.) The Get Invocation Context routine gets the
    invocation context of any active procedure.

    Format

      LIB$GET_INVO_CONTEXT   invo_handle, invo_context

2.102.1  –  Returns

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

2.102.2  –  Arguments

 invo_handle

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

    Handle for the desired invocation. Returned by LIB$GET_INVO_
    HANDLE.

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       write only
    mechanism:    by reference

    Address of an invocation context block into which the procedure
    context of the frame specified by invo_handle will be written.

2.103  –  LIB$GET_INVO_HANDLE

    (Alpha and I64 only.) The Get Invocation Handle routine gets an
    invocation handle of any active procedure.

    A thread can obtain an invocation handle corresponding to any
    invocation context block by using the following function format.

    Format

      LIB$GET_INVO_HANDLE  invo_context

2.103.1  –  Returns

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

    Invocation handle of the invocation context that was passed.
    If the returned value is LIB$K_INVO_HANDLE_NULL, the invocation
    context that was passed was invalid.

2.103.2  –  Argument

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       read only
    mechanism:    by reference

    Address of an invocation context block. Here, only the frame
    pointer and stack pointer fields of an invocation context block
    must be defined.

2.104  –  LIB$GET_LOGICAL

    The Get Logical Name routine calls the system service routine
    $TRNLNM to return information about a logical name.

    Format

      LIB$GET_LOGICAL  logical-name [,resultant-string]

                       [,resultant-length] [,table-name]

                       [,max-index] [,index] [,acmode] [,flags]

2.104.1  –  Returns

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

2.104.2  –  Arguments

 logical-name

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

    Logical name for which LIB$GET_LOGICAL searches. The logical-name
    argument is the address of a descriptor pointing to the logical
    name string.

 resultant-string

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

    Logical name equivalent returned. The resultant-string argument
    is the address of a descriptor pointing to a character string
    into which LIB$GET_LOGICAL writes the equivalence name of the
    logical.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the equivalence name string returned by LIB$GET_
    LOGICAL. The resultant-length argument is the address of an
    unsigned word integer into which LIB$GET_LOGICAL writes the
    length.

 table-name

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

    Name of the table in which to search for the logical name. The
    table-name argument contains the address of a descriptor pointing
    to a character string which contains the table name. If no table
    is specified, LNM$FILE_DEV is used.

 max-index

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

    Largest equivalence name index. Each equivalence name for the
    logical name has an index associated with it. The max-index
    argument is the address of a signed longword integer into which
    LIB$GET_LOGICAL write the value. If no equivalence names (and,
    therefore, no index values) exist, LIB$GET_LOGICAL returns a
    value of -1.

 index

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

    Equivalence name index value. LIB$GET_LOGICAL will return the
    equivalence name string that has the specified index value. The
    index argument is the address of an unsigned longword integer
    specifying the index value.

 acmode

    OpenVMS usage:access_mode
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Access mode to be used in the translation. The acmode argument
    is the address of a byte specifying the access mode. The $PSLDEF
    macro defines symbolic names for the four access modes.

    When you specify the acmode argument, all names at access modes
    which are less privileged than the specified access mode are
    ignored.

    If you do not specify acmode, the translation is performed
    without regard to access mode; however, the translation process
    proceeds from the outermost to the innermost access modes. Thus,
    if two logical names with the same name, but at different access
    modes, exist in the same table, the name with the outermost
    access mode is translated.

 flags

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

    Flags controlling the search for the logical name. The flags
    argument is the address of a longword integer that contains the
    control flags. The $LNMDEF macro defines these flags. Currently
    only bit 0 of this argument is used.

    Bit  Value           Description

    0    LNM$M_CASE_     If set, LIB$GET_LOGICAL does not distinguish
         BLIND           between uppercase and lowercase letters in
                         the logical name to be translated.

    This is an optional argument. If omitted the default is 0.

2.104.3  –  Description

    LIB$GET_LOGICAL provides a simplified interface to the $TRNLNM
    system service. It provides most of the features found in $TRNLNM
    with some additional benefits. For string arguments, all string
    classes supported by the Run-Time Library are understood. The
    list of item descriptors, which may be difficult to construct in
    high-level languages, is handled internally by LIB$GET_LOGICAL.

    See the description of the $TRNLNM system service in the VSI
    OpenVMS System Services Reference Manual for more information.

2.104.4  –  Condition Values Returned

    SS$_NORMAL         Routine successfully completed.
    SS$_ACCVIO         Access violation. Cannot access the location
                       specified.
    SS$_BADPARAM       Bad parameter value.
    SS$_IVLOGNAM       Invalid logical name. The logical name or its
                       value contained more than 255 characters.
    SS$_IVLOGTAB       Invalid logical name table.
    SS$_NOLOGNAM       The logical name was not found in the
                       specified table.
    SS$_NOPRIV         No privileges for attempted operation.
    SS$_TOOMANYNAM     Logical name translation exceeded allowed
                       depth.
    LIB$_INVARG        Required argument is missing.
    LIB$_INSVIRMEM     Insufficient virtual memory.
    LIB$_INVSTRDES     Invalid string descriptor.
    LIB$_STRTRU        Success, but source string truncated.
    LIB$_WRONUMARG     Wrong number of arguments.

2.105  –  LIB$GET_LUN

    The Get Logical Unit Number routine allocates one logical unit
    number from a processwide pool. If a unit is available, its
    number is returned to the caller. Otherwise, an error is returned
    as the function value.

    Format

      LIB$GET_LUN  logical-unit-number

2.105.1  –  Returns

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

2.105.2  –  Argument

 logical-unit-number

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

    Allocated logical unit number or -1 if none was available. The
    logical-unit-number argument is the address of a longword into
    which LIB$GET_LUN returns the value of the allocated logical
    unit. LIB$GET_LUN can allocate logical unit numbers 100 through
    119 on VAX, and 100 through 299 on Alpha and I64.

2.106  –  LIB$GET_MAXIMUM_DATE_LENGTH

    Given an output format and language, the Retrieve the Maximum
    Length of a Date/Time String routine determines the maximum
    possible length for the date-string string returned by
    LIB$FORMAT_DATE_TIME.

    Format

      LIB$GET_MAXIMUM_DATE_LENGTH  date-length [,user-context]

                                   [,flags]

2.106.1  –  Returns

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

2.106.2  –  Arguments

 date-length

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

    Receives the maximum possible length of the date-string argument
    returned to LIB$FORMAT_DATE_TIME. The date-length argument is the
    address of a signed longword that receives this maximum length.
    The length written to date-length reflects the greatest possible
    length of an output date/time string for the currently selected
    output format and natural language.

    For example, if the selected output date/time format includes
    the alphabetic, unabbreviated month name (assuming English as
    the natural language), the longest month name (September) would
    have to be taken into consideration when determining the maximum
    possible length of date-string.

 user-context

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

    Context variable that retains the translation context over
    multiple calls to this routine. The user-context argument is the
    address of an unsigned longword that contains this context. The
    initial value of the context variable must be zero. Thereafter,
    the user program must not write to the cell.

    The user-context parameter is optional. However, if a context
    cell is not passed, the routine LIB$GET_MAXIMUM_DATE_LENGTH
    may abort if two threads of execution attempt to manipulate the
    context area concurrently. Therefore, when calling this routine
    in situations where reentrancy might occur, such as from AST
    level, VSI recommends that users specify a different context cell
    for each calling thread.

 flags

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

    Bit mask that allows the user to specify whether the date, time,
    or both are to be included in the calculation of the maximum date
    length. The flags argument is the address of an unsigned bit mask
    containing the specified values. Valid values are LIB$M_DATE_
    FIELDS and LIB$M_TIME_FIELDS. The values specified for flags must
    correspond to the flags argument passed to LIB$FORMAT_DATE_TIME.

2.107  –  LIB$GET_PREV_INVO_CONTEXT

    (Alpha and I64 only.) The Get Previous Invocation Context routine
    gets the previous invocation context of any active procedure.

    A thread can obtain the invocation context of the procedure
    context preceding any other procedure context using the following
    function format.

    Format

      LIB$GET_PREV_INVO_CONTEXT   invo_context

2.107.1  –  Returns

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

2.107.2  –  Argument

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       modify
    mechanism:    by reference

    Address of an invocation context block. The given context block
    is updated to represent the context of the previous (calling)
    frame.

    For the purposes of this function, the minimum fields of an
    invocation block that must be defined are those IREG and FREG
    fields corresponding to registers used by a context whether the
    registers are preserved or not. Note that the invocation context
    blocks written by the routines specified in these sections define
    all possible fields in a context block. Such context blocks
    satisfy this minimum requirement.

2.108  –  LIB$GET_PREV_INVO_HANDLE

    (Alpha and I64 only.) The Get Previous Invocation Handle routine
    gets the previous invocation handle of any active procedure.

    A thread can obtain an invocation handle of the procedure context
    preceding that of a specified procedure context by using the
    following function format.

    Format

      LIB$GET_PREV_INVO_HANDLE   invo_handle

2.108.1  –  Returns

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

    An invocation handle for the invocation context that is previous
    to that which was specified as the target.

2.108.2  –  Argument

 invo_handle

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

    An invocation handle that represents a target invocation context.

2.109  –  LIB$GET_SYMBOL

    The Get Value of CLI Symbol routine requests the calling
    process's command language interpreter (CLI) to return the value
    of a CLI symbol as a string. LIB$GET_SYMBOL then returns the
    string to the caller. Optionally, LIB$GET_SYMBOL can return the
    length of the returned value and the table in which the symbol
    was found.

    Format

      LIB$GET_SYMBOL  symbol ,resultant-string [,resultant-length]

                      [,table-type-indicator]

2.109.1  –  Returns

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

2.109.2  –  Arguments

 symbol

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

    Name of the symbol for which LIB$GET_SYMBOL searches. The symbol
    argument is the address of a descriptor pointing to the name
    of the symbol. LIB$GET_SYMBOL converts the symbol name to
    uppercase and removes trailing blanks before the search. The
    symbol argument must begin with a letter, a digit, a dollar sign
    ($),  a hyphen (-), or an underscore (_).  The maximum length of
    symbol is 255 characters.

 resultant-string

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

    Value of the returned symbol. The resultant-string argument is
    the address of a descriptor pointing to a character string into
    which LIB$GET_SYMBOL writes the value of the symbol.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the symbol value returned by LIB$GET_SYMBOL. The
    resultant-length argument is the address of an unsigned word
    integer into which LIB$GET_SYMBOL writes the length.

 table-type-indicator

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

    Indicator of which table contained the symbol. The table-type-
    indicator argument is the address of a signed longword integer
    into which LIB$GET_SYMBOL writes the table indicator.

    Possible values of the table indicator are listed below.

    Symbolic Name       Value Table

    LIB$K_CLI_LOCAL_    1     Local symbol table
    SYM
    LIB$K_CLI_GLOBAL_   2     Global symbol table
    SYM

    LIB$K_CLI_LOCAL_SYM and LIB$K_CLI_GLOBAL_SYM are defined in
    symbol libraries supplied by VSI (macro or module name $LIBCLIDEF)
    and as global symbols.

2.110  –  LIB$GET_UIB_INFO

    Returns information from the unwind information block (UIB).

    Format

      LIB$GET_UIB_INFO  uib_va [,gp_value] [,uw_desc_va]

                        [,uw_desc_len] [,handler_fv] [,ossd_va]

                        [,lsda_va]

2.110.1  –  Returns

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

2.110.2  –  Arguments

 uib_va

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        read only
    mechanism:     by reference
    Address of a quadword that contains the virtual address of an
    unwind information block (UIB).

 gp_value

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        read only
    mechanism:     by reference
    Address of a quadword that contains the GP value that must be
    added to the UIB condition handler value. Must be specified if
    handler_fv is specified.

 uw_desc_va

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        write
    mechanism:     by reference
    Address of a quadword to store the virtual address of the unwind
    descriptor area. If none is present, then zero is returned. This
    is an optional argument.

 un_desc_len

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        write
    mechanism:     by reference
    Address of a quadword to store the length (in bytes) of the
    unwind descriptor area. If none are present, then zero is
    returned. This is an optional argument.

 handler_fv

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        write
    mechanism:     by reference
    Address of a quadword to store the function value of the
    condition handler. If none is present, then zero is returned.
    This is an optional argument.

 ossd_va

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        write
    mechanism:     by reference
    Address of a quadword to store the address of the operating
    system-specific data area. If none is present, then zero is
    returned. This is an optional argument.

 lsda_va

    OpenVMS usage: address
    type:          quadword (unsigned)
    access:        write
    mechanism:     by reference
    Address of a quadword to store the address of the language-
    specific data area (LSDA). If none is present, then zero is
    returned. This is an optional argument.

2.110.3  –  Description

    Takes in the address of an uwind information block (UIB) and the
    GP value for a routine and returns the addresses of the start of
    the unwind descriptors (if any), the handler function descriptor
    (if any), and the operating system-specific data area (if any).
    The size in bytes of the unwind descriptors is also returned.

    Related Services

    SYS$SET_UNWIND_TABLE, SYS$CLEAR_UNWIND_TABLE, SYS$GET_UNWIND_
    ENTRY_INFO,

2.110.4  –  Condition Values Returned

    SS$_NORMAL         Routine completed successfully.
    LIB$_INVARG        Bad UIB virtual address.

2.111  –  LIB$GET_USERS_LANGUAGE

    The Return the User's Language routine determines the user's
    choice of a natural language. The choice is determined by
    translating the logical SYS$LANGUAGE.

    Format

      LIB$GET_USERS_LANGUAGE  language

2.111.1  –  Returns

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

2.111.2  –  Argument

 language

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

    Receives the translation of SYS$LANGUAGE. The language argument
    is the address of a descriptor pointing to this language name.

2.112  –  LIB$GET_VM

    The Allocate Virtual Memory routine allocates a specified number
    of contiguous bytes in the program region and returns the 32-bit
    virtual address of the first byte allocated.

    Format

      LIB$GET_VM  number-of-bytes, base-address [,zone-id]

2.112.1  –  Returns

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

2.112.2  –  Arguments

 number-of-bytes

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

    Number of contiguous bytes that LIB$GET_VM allocates. The number-
    of-bytes argument is the address of a longword integer containing
    the number of bytes. LIB$GET_VM allocates enough memory to
    satisfy the request. Your program should not reference an address
    before the first byte address allocated (base-address) or beyond
    the last byte allocated (base-address + number-of-bytes-1) since
    that space may be assigned to another routine. The value of
    number-of-bytes must be greater than zero.

 base-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    First virtual address of the contiguous block of bytes allocated
    by LIB$GET_VM. The base-address argument is the address of an
    unsigned longword containing this base address.

 zone-id

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

    The zone-id argument is the address of a longword that contains a
    zone identifier created by a previous call to LIB$CREATE_VM_ZONE
    or LIB$CREATE_USER_VM_ZONE. This argument is optional. If zone-id
    is omitted or if the longword contains the value 0, the 32-bit
    default zone is used.

2.113  –  LIB$GET_VM_64

    (Alpha and I64 only.) The Allocate Virtual Memory routine
    allocates a specified number of contiguous bytes in the program
    region and returns the 64-bit virtual address of the first byte
    allocated.

    Format

      LIB$GET_VM_64  number-of-bytes, base-address [,zone-id]

2.113.1  –  Returns

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

2.113.2  –  Arguments

 number-of-bytes

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Number of contiguous bytes that LIB$GET_VM_64 allocates. The
    number-of-bytes argument is the address of a quadword integer
    containing the number of bytes. LIB$GET_VM_64 allocates enough
    memory to satisfy the request. Your program should not reference
    an address before the first byte address allocated (base-address)
    or beyond the last byte allocated (base-address + number-of-bytes
    minus 1) since that space may be assigned to another routine. The
    value of number-of-bytes must be greater than zero.

 base-address

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    First virtual address of the contiguous block of bytes allocated
    by LIB$GET_VM_64. The base-address argument is the address of an
    unsigned quadword containing this base address.

 zone-id

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    The zone-id argument is the address of a quadword that contains a
    zone identifier created by a previous call to LIB$CREATE_VM_ZONE_
    64 or LIB$CREATE_USER_VM_ZONE_64. This argument is optional. If
    zone-id is omitted or if the quadword contains the value 0, the
    64-bit default zone is used.

2.114  –  LIB$GET_VM_PAGE

    The Get Virtual Memory Page routine allocates a specified number
    of contiguous pages on VAX systems or pagelets on Alpha and I64
    systems of memory in the program region and returns the virtual
    address of the first allocated page on VAX or pagelet on Alpha or
    I64.

    Format

      LIB$GET_VM_PAGE  number-of-pages ,base-address

2.114.1  –  Returns

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

2.114.2  –  Arguments

 number-of-pages

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

    Number of pages on VAX systems or pagelets on Alpha and I64
    systems. The number-of-pages argument is the address of a
    longword integer that specifies the number of contiguous pages on
    VAX systems or pagelets on Alpha and I64 systems to be allocated.
    The value of number-of-pages must be greater than 0.

 base-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Block address. The base-address argument is the address of a
    longword that is set to the address of the first byte of the
    newly allocated block of pages on VAX systems or pagelets on
    Alpha and I64 systems.

2.115  –  LIB$GET_VM_PAGE_64

    (Alpha and I64 only.) The Get Virtual Memory Page routine
    allocates a specified number of contiguous Alpha or I64 pagelets
    of memory in the program region and returns the virtual address
    of the first allocated pagelet.

    Format

      LIB$GET_VM_PAGE_64  number-of-pages ,base-address

2.115.1  –  Returns

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

2.115.2  –  Arguments

 number-of-pages

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Number of Alpha or I64 pagelets. The number-of-pages argument is
    the address of a quadword integer that specifies the number of
    contiguous Alpha or I64 pagelets to be allocated. The value of
    number-of-pages must be greater than 0.

 base-address

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Block address. The base-address argument is the address of a
    quadword that is set to the address of the first byte of the
    newly allocated block of Alpha or I64 pagelets.

2.116  –  LIB$I64_GET_CURR_INVO_CONTEXT

    (I64 only.) The Get Current Invocation Context routine gets the
    invocation context of a current procedure.

    Format

      LIB$I64_GET_CURR_INVO_CONTEXT   invo_context

2.116.1  –  Returns

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

2.116.2  –  Argument

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       modify only
    mechanism:    by reference

    Address of an invocation context block into which the procedure
    context of the caller will be written.

2.117  –  LIB$I64_GET_CURR_INVO_HANDLE

    (I64 only.) The Get Current Invocation Handle routine gets the
    invocation handle for the current procedure.

    Format

      LIB$I64_GET_CURR_INVO_HANDLE  invo_handle

2.117.1  –  Returns

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

2.117.2  –  Argument

 invo_handle

    OpenVMS usage:invo_handle
    type:         quadword
    access:       write only
    mechanism:    by reference

    Address of a quadword into which the invocation handle of the
    caller will be written.

2.118  –  LIB$I64_GET_FR

    (I64 only.) The Get Floating-Point Register routine copies the
    value of the floating-point register.

    Format

      LIB$I64_GET_FR   invo_context, index, fr_copy

2.118.1  –  Returns

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

2.118.2  –  Argument

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       read
    mechanism:    by reference

    Address of a valid invocation context block.

 index

    OpenVMS usage:index
    type:         longword
    access:       read
    mechanism:    by value

    Floating point register index.

 fr_copy

    OpenVMS usage:floating-point value
    type:         octaword
    access:       write
    mechanism:    by value

    Address of an octaword to receive the contents of the specified
    floating-point register.

2.119  –  LIB$I64_GET_INVO_CONTEXT

    (I64 only.) The Get Invocation Context routine gets the
    invocation context of any active procedure.

    Format

      LIB$I64_GET_INVO_CONTEXT   invo_handle, invo_context

2.119.1  –  Returns

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

2.119.2  –  Arguments

 invo_handle

    OpenVMS usage:invo_handle
    type:         quadword
    access:       modify only
    mechanism:    by reference

    Address of an invocation context block into which the procedure
    context of the frame specified by invo_handle will be written.

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       write only
    mechanism:    by reference

    Address of an invocation context block into which the procedure
    context of the frame specified by invo_handle will be written.

2.120  –  LIB$GET_INVO_HANDLE

    (I64 only.) The Get Invocation Handle routine obtains the
    invocation handle corresponding to any invocation context block.

    Format

      LIB$I64_GET_INVO_HANDLE   invo_context, invo_handle

2.120.1  –  Returns

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

2.120.2  –  Arguments

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       read only
    mechanism:    by reference

    Address of a valid invocation context block.

 invo_handle

    OpenVMS usage:invo_handle
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Address of the location into which the invocation context handle
    is to be written. If the call fails, the value of the invocation
    context handle is LIB$K_INVO_HANDLE_NULL.

2.121  –  LIB$I64_GET_PREV_INVO_CONTEXT

    (I64 only.) The Get Current Invocation Context routine obtains
    the invocation context of the procedure context preceding any
    other procedure context.

    Format

      LIB$I64_GET_PREV_INVO_CONTEXT   invo_context

2.121.1  –  Returns

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

2.121.2  –  Argument

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       modify only
    mechanism:    by reference

    Address of a valid invocation context block. The given invocation
    context block is updated to represent the context of the previous
    (calling) frame.

    The LIBICB$V_BOTTOM_OF_STACK flag of the invocation context block
    is set if the target frame represents the end of the invocation
    call chain or if stack corruption is detected.

2.122  –  LIB$I64_GET_PREV_INVO_HANDLE

    (I64 only.) The Get Previous Invocation Handle routine gets an
    invocation handle of the procedure context preceding that of a
    specified procedure context.

    Format

      LIB$I64_GET_PREV_INVO_HANDLE  invo_handle_in, invo_handle_out

2.122.1  –  Returns

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

2.122.2  –  Argument

 invo_handle_in

    OpenVMS usage:invo_handle
    type:         quadword
    access:       read only
    mechanism:    by reference

    The address of an invocation handle that represents a target
    invocation context.

 invo_handle_out

    OpenVMS usage:invo_handle
    type:         quadword
    access:       write only
    mechanism:    by reference

    Address of the location into which the invocation context handle
    of the previous context is to be written. If the call fails, the
    value of the previous invocation context handle is LIB$K_INVO_
    HANDLE_NULL.

2.123  –  LIB$I64_GET_UNWIND_HANDLER_FV

    (I64 only.) The Get Function Value For Condition Handler routine
    finds the function value (address of the procedure descriptor)
    for the condition handler.

    Format

      LIB$I64_GET_UNWIND_HANDLER_FV   pc_value, handler_fv

2.123.1  –  Returns

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

2.123.2  –  Arguments

 pc_value

    OpenVMS usage:PC value
    type:         quadword
    access:       read
    mechanism:    by reference

    Address of a location that contains the PC value.

    pc_value is used to find the unwind information block and the
    unwind information block condition handler pointer.

 handler_fv

    OpenVMS usage:address
    type:         quadword
    access:       write
    mechanism:    by reference

    A quadword to receive the function value of the procedure
    descriptor for the condition handler, if there is one.

2.124  –  LIB$I64_GET_UNWIND_LSDA

    (I64 only.) The Find Address of Unwind Information Block
    Language-Specific Data routine finds the address of the unwind
    information block language-specific data area.

    Format

      LIB$I64_GET_UNWIND_LSDA   pc_value, unwind_lsda_p

2.124.1  –  Returns

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

2.124.2  –  Arguments

 pc_value

    OpenVMS usage:PC value
    type:         quadword
    access:       read
    mechanism:    by reference

    Address of a quadword to receive the address of the language-
    specific data area, if there is one.

 unwind_lsda_p

    OpenVMS usage:address
    type:         quadword
    access:       write
    mechanism:    by reference

    Address of a location that contains the PC value. pc_value
    is used to find the unwind information block and the unwind
    information block language-specific data area address.

2.125  –  LIB$I64_GET_UNWIND_OSSD

    (I64 only.) The Find Address of the Unwind Information Block
    Operating System-Specific Data Area routine finds the address of
    the unwind information block operating system-specific data area.

    Format

      LIB$I64_GET_UNWIND_OSSD   pc_value, unwind_ossd_p

2.125.1  –  Returns

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

2.125.2  –  Argument

 pc_value

    OpenVMS usage:PC value
    type:         quadword
    access:       read
    mechanism:    by reference

    Address of a location that contains the PC value. pc_value
    is used to find the unwind information block and the unwind
    information block operating system-specific data area address.

 unwind_ossd_p

    OpenVMS usage:address
    type:         quadword
    access:       write
    mechanism:    by reference

    Address of a quadword to receive the address of the operating
    system-specific data area.

2.126  –  LIB$I64_IS_AST_DISPATCH_FRAME

    (I64 only.) The Determine AST Exception Frame Dispatch routine
    determines whether a given PC value represents an AST dispatch
    frame.

    Format

      LIB$I64_IS_AST_DISPATCH_FRAME   pc_value

2.126.1  –  Returns

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

2.126.2  –  Argument

 pc_value

    OpenVMS usage:PC value
    type:         quadword
    access:       read
    mechanism:    by reference

    Address of a quadword that contains the PC value.

    The pc_value is used to find the operating system-specific data
    area in the unwind information for this routine.

2.127  –  LIB$I64_IS_EXC_DISPATCH_FRAME

    (I64 only.) The Determine Exception Frame Dispatch routine
    determines whether a given PC value represents an exception
    dispatch frame.

    Format

      LIB$I64_IS_EXC_DISPATCH_FRAME   pc_value

2.127.1  –  Returns

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

2.127.2  –  Argument

 pc_value

    OpenVMS usage:PC value
    type:         quadword
    access:       read
    mechanism:    by reference

    Address of a quadword that contains the PC value.

    The pc_value is used to find the operating system-specific data
    area in the unwind information for this routine.

2.128  –  LIB$I64_PREV_INVO_END

    (I64 only.) The End Call Tracing Operations routine should be
    called at the conclusion of call tracing operations to free the
    memory used to process unwind descriptors.

    Format

      LIB$I64_PREV_INVO_END    (invo_context)

2.128.1  –  Returns

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

2.128.2  –  Argument

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       modify only
    mechanism:    by reference

    Address of a valid invocation context block previously used for
    call tracing.

2.129  –  LIB$I64_PUT_INVO_REGISTERS

    (I64 only.) The Put Invocation Registers routine updates the
    fields of a given procedure invocation context.

    Note that if user override routines are specified in the
    invocation context block, then they are used to find and modify
    the invocation context.

    Format

      LIB$I64_PUT_INVO_REGISTERS   invo_handle, invo_context,

                                   [,gr_mask] [,fr_mask]

                                   [,br_mask] [,pr_mask] [,misc_mask]

2.129.1  –  Returns

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

2.129.2  –  Arguments

 invo_handle

    OpenVMS usage:invo_handle
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Handle for the invocation to be updated.

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       read only
    mechanism:    by reference

    Address of a valid invocation context block that contains new
    register contents.

    Each register that is set in the xx_mask argument (along with
    its NaT bit, if any) is updated using the value found in the
    corresponding IREG[n], FREG[n], BRANCH[n], or PRED[n] field. GP,
    TP, and AI can also be updated in this way.

    No other fields of the invocation context block are used.

 gr_mask

    OpenVMS usage:mask_octaword
    type:         128-bit vector
    access:       read only
    mechanism:    by reference

    Address of a 128-bit bit vector, where each bit corresponds to a
    register field in the invo_context argument. Bits 0 through 127
    correspond to IREG[0] through IREG[127].

    Bit 0 corresponds to R0, which cannot be written, and is ignored.

    Bit 1 corresponds to the global data pointer (GP).

    Bit 13 corresponds to the thread pointer (TP).

    Bit 25 corresponds to the argument information register (AI).

    If bit 12, which corresponds to SP, is set, then no changes are
    made.

 fr_mask

    OpenVMS usage:mask_octaword
    type:         128-bit vector
    access:       read only
    mechanism:    by reference

    Address of a 128-bit bit vector, where each bit corresponds to a
    register field in the passed invo_context.

    To update floating-point registers F32-F127, provide a pointer to
    an array of 96 octawords in LIBICB$PH_F32_F127.

    Bits 0 through 127 correspond to FREG[0] through FREG[127].

    Bit 0 corresponds to F0, which cannot be written, and is ignored.
    Bit 1 corresponds to F1, which cannot be written, and is ignored.

 br_mask

    OpenVMS usage:mask_byte
    type:         8-bit vector
    access:       read only
    mechanism:    by reference

    Address of a 8-bit bit vector, where each bit corresponds to
    a register field in the passed invo_context. Bits 0 through 7
    correspond to BRANCH[0] through BRANCH[7].

 pr_mask

    OpenVMS usage:mask_quadword
    type:         64-bit vector
    access:       read only
    mechanism:    by reference

    Address of a 64-bit bit vector, where each bit corresponds to
    a register field in the passed invo_context. Bits 0 through 63
    correspond to PRED[0] through PRED[63].

 misc_mask

    OpenVMS usage:mask_quadword
    type:         64-bit vector
    access:       read only
    mechanism:    by reference

    Address of a 64-bit bit vector, where each bit corresponds to a
    register field in the passed invo_context as follows:

       Bit 0=PC.
       Bit 1=FPSR.
       Bits 2-63 are reserved.

2.130  –  LIB$I64_SET_FR

    (I64 only.) The Set Floating-Point Register routine writes
    the invocation context block floating-point registry entry
    corresponding to a floating-point register value.

    Format

      LIB$I64_SET_FR   invo_context, index, fr_copy

2.130.1  –  Returns

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

2.130.2  –  Arguments

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       modify
    mechanism:    by reference

    Address of a valid invocation context block.

 index

    OpenVMS usage:index
    type:         longword
    access:       read
    mechanism:    by value

    Index into the FREG array of the invocation context block.

 fr_copy

    OpenVMS usage:floating-point value
    type:         octaword
    access:       write
    mechanism:    by value

    Address of an octaword that contains the floating-point value to
    be written to the invocation context block.

2.131  –  LIB$I64_SET_GR

    (I64 only.) The Copy Invocation Block General Register routine
    writes the invocation context block general register.

    Format

      LIB$I64_SET_GR   invo_context, index, fr_copy

2.131.1  –  Returns

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

2.131.2  –  Arguments

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       modify
    mechanism:    by reference

    Address of a valid invocation context block.

 index

    OpenVMS usage:index
    type:         longword
    access:       read
    mechanism:    by value

    Index into the IREG array of the invocation context block.

 gr_copy

    OpenVMS usage:integer value
    type:         quadword
    access:       write
    mechanism:    by value

    Address of a quadword that contains the value to be written to
    the invocation context block.

2.132  –  LIB$I64_SET_PC

    (I64 only.) The Write Context Block and Quadword PC Value routine
    writes invocation context block PC.

    Format

      LIB$I64_SET_PC   invo_context, pc_copy

2.132.1  –  Returns

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

2.132.2  –  Arguments

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       modify
    mechanism:    by reference

    Address of a valid invocation context block.

 pc_copy

    OpenVMS usage:PC value
    type:         quadword
    access:       read
    mechanism:    by reference

    Address of a quadword that contains the PC value to be written to
    the invocation context block.

2.133  –  LIB$ICHAR

    The Convert First Character of String to Integer routine converts
    the first character of a source string to an 8-bit ASCII integer
    extended to a longword.

    Format

      LIB$ICHAR  source-string

2.133.1  –  Returns

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

    First character of the source string. This character is returned
    by LIB$ICHAR as an 8-bit ASCII value extended to a longword. If
    the source string has zero length, LIB$ICHAR returns a zero.

2.133.2  –  Argument

 source-string

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

    Source string whose first character is converted to an integer
    by LIB$ICHAR. The source-string argument is the address of a
    descriptor pointing to this source string.

2.134  –  LIB$INDEX

    The Index to Relative Position of Substring routine returns an
    index, which is the relative position of the first occurrence of
    a substring in the source string.

    Format

      LIB$INDEX  source-string ,sub-string

2.134.1  –  Returns

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

    The relative position of the first character of the substring if
    found, or zero if not found.

    On Alpha and I64 systems, if the relative position of the
    substring can exceed 2**32-1, assign the return value to a
    quadword to ensure that you retrieve the correct relative
    position.

2.134.2  –  Arguments

 source-string

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

    Source string to be searched by LIB$INDEX. The source-string
    argument is the address of a descriptor pointing to this source
    string.

 sub-string

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

    Substring to be found. The sub-string argument is the address of
    a descriptor pointing to this substring.

2.135  –  LIB$INIT_DATE_TIME_CONTEXT

    The Initialize the Context Area Used in Formatting Dates and
    Times for Input or Output routine allows the user to initialize
    the context area used by LIB$FORMAT_DATE_TIME or LIB$CONVERT_
    DATE_STRING with specific strings, instead of through logical
    name translation.

    Format

      LIB$INIT_DATE_TIME_CONTEXT  user-context ,component

                                  ,init-string

2.135.1  –  Returns

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

2.135.2  –  Arguments

 user-context

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

    User context that retains the translation context over multiple
    calls to this routine. The user-context argument is the address
    of an unsigned longword that contains this context. The initial
    value of the context variable must be zero. Thereafter, the user
    program must not write to the cell.

 component

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

    The component of the context that is being initialized. The
    component argument is the address of a signed longword that
    indicates this component. Only one component can be initialized
    per call to LIB$INIT_DATE_TIME; these component codes are shown
    in the following list.

    o  LIB$K_MONTH_NAME

    o  LIB$K_MONTH_NAME_ABB

    o  LIB$K_FORMAT_MNEMONICS

    o  LIB$K_WEEKDAY_NAME

    o  LIB$K_WEEKDAY_NAME_ABB

    o  LIB$K_RELATIVE_DAY_NAME

    o  LIB$K_MERIDIEM_INDICATOR

    o  LIB$K_OUTPUT_FORMAT

    o  LIB$K_INPUT_FORMAT

    o  LIB$K_LANGUAGE

 init-string

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

    The characters that are to be used in formatting dates and times
    for input or output. The init-string argument is the address of a
    descriptor pointing to this string.

2.136  –  LIB$INIT_TIMER

    The Initialize Times and Counts routine stores the current
    values of specified times and counts for use by LIB$SHOW_TIMER
    or LIB$STAT_TIMER.

    Format

      LIB$INIT_TIMER  [context]

2.136.1  –  Returns

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

2.136.2  –  Argument

 context

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

    Context variable that retains the values of the times and counts.
    The context argument contains the address of an unsigned longword
    that is this context. When you call LIB$INIT_TIMER, you must
    use the optional context argument only if you want to maintain
    several sets of statistics simultaneously.

    o  If context is omitted, the control block is allocated in
       static storage. This method is not AST reentrant.

    o  If context is zero, a control block is allocated in dynamic
       heap storage. The times and counts will be stored in that
       block and the address of the block returned in context. This
       method is fully reentrant and modular.

    o  If context is nonzero, it is considered to be the address of
       a control block previously allocated by a call to LIB$INIT_
       TIMER. If so, the control block is reused, and fresh times and
       counts are stored in it.

    When LIB$INIT_TIMER returns, the block of storage referred to by
    context will contain the times and counts.

2.137  –  LIB$INSERT_TREE

    The Insert Entry in a Balanced Binary Tree routine inserts a node
    in a balanced binary tree.

    Format

      LIB$INSERT_TREE  treehead ,symbol ,flags ,user-compare-routine

                       ,user-allocation-procedure ,new-node

                       [,user-data]

2.137.1  –  Returns

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

2.137.2  –  Arguments

 treehead

    OpenVMS usage:address
    type:         address
    access:       modify
    mechanism:    by reference

    Tree head for the binary tree. The treehead argument is the
    address of a longword that is this tree head. The initial value
    of treehead is 0.

 symbol

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       unspecified
    mechanism:    unspecified

    Key to be inserted.

 flags

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

    Control flags. The flags argument is the address of the control
    flags. Currently only bit 0 is used.

    Bit  Action if Set    Action if Clear

    0    Duplicate        The address of the existing duplicate entry
         entries are      is returned to the new-node argument.
         inserted.

 user-compare-routine

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

    User-supplied compare routine that LIB$INSERT_TREE calls to
    compare a symbol with a node. The user-compare-routine argument
    is required; LIB$INSERT_TREE calls the compare routine for every
    node except the first node in the tree. The value returned by the
    compare routine indicates the relationship between the symbol key
    and the node.

 user-allocation-procedure

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

    User-supplied allocate routine that LIB$INSERT_TREE calls to
    allocate virtual memory for a node. The user-allocation-procedure
    argument is required; LIB$INSERT_TREE always calls the allocate
    routine.

 new-node

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Location where the new key is inserted. The new-node argument is
    the address of an unsigned longword that is the address of the
    new node.

 user-data

    OpenVMS usage:user_arg
    type:         unspecified
    access:       unspecified
    mechanism:    by value

    User data that LIB$INSERT_TREE passes to the compare and allocate
    routines. The user-data argument is optional.

2.138  –  LIB$INSERT_TREE_64

    (Alpha and I64 only.) The Insert Entry in a Balanced Binary Tree
    routine inserts a node in a balanced binary tree.

    Format

      LIB$INSERT_TREE_64  treehead ,symbol ,flags

                          ,user-compare-routine

                          ,user-allocation-procedure ,new-node

                          [,user-data]

2.138.1  –  Returns

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

2.138.2  –  Arguments

 treehead

    OpenVMS usage:address
    type:         address
    access:       modify
    mechanism:    by reference

    Tree head for the binary tree. The treehead argument is the
    address of a quadword that is this tree head. The initial value
    of treehead is 0.

 symbol

    OpenVMS usage:user_arg
    type:         quadword (unsigned)
    access:       unspecified
    mechanism:    unspecified

    Key to be inserted.

 flags

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Control flags. The flags argument is the address of the control
    flags. Currently only bit 0 is used.

    Bit   Description

    0     If clear, the address of the existing duplicate entry
          is returned to the new-node argument. If set, duplicate
          entries are inserted.

 user-compare-routine

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

    User-supplied compare routine that LIB$INSERT_TREE_64 calls to
    compare a symbol with a node. The user-compare-routine argument
    is required; LIB$INSERT_TREE_64 calls the compare routine for
    every node except the first node in the tree. The value returned
    by the compare routine indicates the relationship between the
    symbol key and the node.

 user-allocation-procedure

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

    User-supplied allocate routine that LIB$INSERT_TREE_64 calls
    to allocate virtual memory for a node. The user-allocation-
    procedure argument is required; LIB$INSERT_TREE_64 always calls
    the allocate routine.

 new-node

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Location where the new key is inserted. The new-node argument is
    the address of an unsigned quadword that is the address of the
    new node.

 user-data

    OpenVMS usage:user_arg
    type:         unspecified
    access:       unspecified
    mechanism:    by value

    User data that LIB$INSERT_TREE_64 passes to the compare and
    allocate routines. The user-data argument is optional.

2.139  –  LIB$INSQHI

    The Insert Entry at Head of Queue routine inserts a queue entry
    at the head of the specified self-relative longword interlocked
    queue. LIB$INSQHI makes the INSQHI instruction available as a
    callable routine.

    Format

      LIB$INSQHI  entry ,header [,retry-count]

2.139.1  –  Returns

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

2.139.2  –  Arguments

 entry

    OpenVMS usage:unspecified
    type:         unspecified
    access:       modify
    mechanism:    by reference, array reference

    Entry to be inserted by LIB$INSQHI. The entry argument contains
    the address of this signed quadword-aligned array that must be at
    least 8 bytes long. Bytes following the first 8 bytes can be used
    for any purpose by the calling program.

    For Alpha and I64 systems, the entry argument must contain a 32-
    bit sign-extended address. An illegal operand exception occurs
    for any other form of address.

 header

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       modify
    mechanism:    by reference

    Queue header specifying the queue into which entry is to be
    inserted. The header argument contains the address of this signed
    aligned quadword integer. The header argument must be initialized
    to zero before first use of the queue; zero means an empty queue.

    For Alpha systems, the header argument must contain a 32-bit
    sign-extended address. An illegal operand exception occurs for
    any other form of address.

 retry-count

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

    The number of times the insertion is to be retried in case
    of secondary-interlock failure of the queue instruction in a
    processor-shared memory application. The retry-count argument is
    the address of an unsigned longword that contains the retry count
    value. A value of 1 causes no retries. The default value is 10.

2.140  –  LIB$INSQHIQ

    (Alpha and I64 only.) The Insert Entry at Head of Queue routine
    inserts a queue entry at the head of the specified self-relative
    quadword interlocked queue. LIB$INSQHIQ makes the INSQHIQ
    instruction available as a callable routine.

    Format

      LIB$INSQHIQ  entry ,header [,retry-count]

2.140.1  –  Returns

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

2.140.2  –  Arguments

 entry

    OpenVMS usage:unspecified
    type:         unspecified
    access:       modify
    mechanism:    by reference, array reference

    Entry to be inserted by LIB$INSQHIQ. The entry argument contains
    the address of this signed octaword-aligned array that must be
    at least 16 bytes long. Bytes following the first 16 bytes can be
    used for any purpose by the calling program.

 header

    OpenVMS usage:octaword_signed
    type:         octaword integer (signed)
    access:       modify
    mechanism:    by reference

    Queue header specifying the queue into which entry is to be
    inserted. The header argument contains the address of this signed
    aligned octaword integer. The header argument must be initialized
    to zero before first use of the queue; zero means an empty queue.

 retry-count

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

    The number of times the insertion is to be retried in case
    of secondary-interlock failure of the queue instruction in a
    processor-shared memory application. The retry-count argument is
    the address of an unsigned longword that contains the retry count
    value. A value of 1 causes no retries. The default value is 10.

2.141  –  LIB$INSQTI

    The Insert Entry at Tail of Queue routine inserts a queue entry
    at the tail of the specified self-relative longword interlocked
    queue. LIB$INSQTI makes the INSQTI instruction available as a
    callable routine.

    Format

      LIB$INSQTI  entry ,header [,retry-count]

2.141.1  –  Returns

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

2.141.2  –  Arguments

 entry

    OpenVMS usage:unspecified
    type:         unspecified
    access:       modify
    mechanism:    by reference, array reference

    Entry to be inserted at the tail of the queue by LIB$INSQTI.
    The entry argument contains the address of this signed quadword-
    aligned array that must be at least 8 bytes long. Bytes following
    the first 8 bytes can be used for any purpose by the calling
    program.

    For Alpha and I64 systems, the entry argument must contain a 32-
    bit sign-extended address. An illegal operand exception occurs
    for any other form of address.

 header

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       modify
    mechanism:    by reference

    Queue header specifying the queue into which the queue entry is
    to be inserted. The header argument contains the address of this
    signed aligned quadword integer. The header argument must be
    initialized to zero before first use of the queue; zero means an
    empty queue.

    For Alpha and I64 systems, the header argument must contain a
    32-bit sign-extended address. An illegal operand exception occurs
    for any other form of address.

 retry-count

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

    The number of times the insertion is to be retried in case
    of secondary-interlock failure of the queue instruction in a
    processor-shared memory application. The retry-count argument is
    the address of a longword which contains the retry count value.
    The default value is 10.

2.142  –  LIB$INSQTIQ

    (Alpha and I64 only.) The Insert Entry at Tail of Queue routine
    inserts a queue entry at the tail of the specified self-relative
    quadword interlocked queue. LIB$INSQTIQ makes the INSQTIQ
    instruction available as a callable routine.

    Format

      LIB$INSQTIQ  entry ,header [,retry-count]

2.142.1  –  Returns

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

2.142.2  –  Arguments

 entry

    OpenVMS usage:unspecified
    type:         unspecified
    access:       modify
    mechanism:    by reference, array reference

    Entry to be inserted at the tail of the queue by LIB$INSQTIQ. The
    entry argument contains the address of this signed octaword-
    aligned array that must be at least 16 bytes long. Bytes
    following the first 16 bytes can be used for any purpose by the
    calling program.

 header

    OpenVMS usage:octaword_signed
    type:         octaword integer (signed)
    access:       modify
    mechanism:    by reference

    Queue header specifying the queue into which the queue entry is
    to be inserted. The header argument contains the address of this
    signed aligned octaword integer. The header argument must be
    initialized to zero before first use of the queue; zero means an
    empty queue.

 retry-count

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

    The number of times the insertion is to be retried in case
    of secondary-interlock failure of the queue instruction in a
    processor-shared memory application. The retry-count argument is
    the address of a longword that contains the retry count value.
    The default value is 10.

2.143  –  LIB$INSV

    The Insert a Variable Bit Field routine replaces the variable bit
    field specified by the base, position, and size arguments with
    bits 0 through (size-1) of the source field. If the size of the
    bit field is zero, nothing is inserted. LIB$INSV makes the VAX
    INSV instruction available as a callable routine.

    Format

      LIB$INSV  longword-integer-source ,position ,size ,base-address

2.143.1  –  Returns

    None.

2.143.2  –  Arguments

 longword-integer-source

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

    Source field to be inserted by LIB$INSV. The  longword-integer-
    source argument is the address of a signed longword integer that
    contains this source field.

 position

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

    Bit position relative to the base address where insertion of
    longword-integer-source is to begin. The position argument is
    the address of a longword integer that contains this relative bit
    position.

 size

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Size of the bit field to be inserted by LIB$INSV. The size
    argument is the address of an unsigned byte that contains the
    size of this bit field. The maximum size is 32 bits.

 base-address

    OpenVMS usage:address
    type:         address
    access:       read only
    mechanism:    by value

    Field into which LIB$INSV writes the source field. The base-
    address argument is an unsigned longword containing the base
    address of this aligned bit string.

2.144  –  LIB$INT_OVER

    The Integer Overflow Detection routine enables or disables
    integer overflow detection for the calling routine activation.
    The previous integer overflow enable setting is returned.

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

    Format

      LIB$INT_OVER  new-setting

2.144.1  –  Returns

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

    Old integer overflow enable setting (the previous contents of
    SF$W_PSW[PSW$V_IV] in the caller's frame).

2.144.2  –  Argument

  new-setting

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

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

2.145  –  LIB$LEN

    The Length of String Returned as Longword Value routine returns
    the length of a string.

    Format

      LIB$LEN  source-string

2.145.1  –  Returns

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by value

    Length of the source string, extracted and zero-extended to 32
    bits.

2.145.2  –  Argument

 source-string

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

    Source string whose length is returned by LIB$LEN. The source-
    string argument contains the address of a descriptor pointing to
    this source string.

2.146  –  LIB$LOCC

    The Locate a Character routine locates a character in a string
    by comparing successive bytes in the string with the character
    specified. The search continues until the character is found or
    the string has no more characters. LIB$LOCC makes the VAX LOCC
    instruction available as a callable routine.

    Format

      LIB$LOCC  character-string ,source-string

2.146.1  –  Returns

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

    The relative position from the start of source-string to the
    first equal character or zero if no match is found.

2.146.2  –  Arguments

 character-string

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

    String whose initial character is used by LIB$LOCC in the
    search. The character-string argument contains the address of
    a descriptor pointing to this string. Only the first character of
    character-string is used, and its length is not checked.

 source-string

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

    String to be searched by LIB$LOCC. The source-string argument is
    the address of a descriptor pointing to this character string.

2.147  –  LIB$LOCK_IMAGE

    Locks the specified image in the process's working set.

    Format

      LIB$LOCK_IMAGE  address

2.147.1  –  Returns

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

2.147.2  –  Argument

 address

    OpenVMS usage:address
    type:         quadword
    access:       read only
    mechanism:    by value

    Address of a byte within the image to be locked in the working
    set. If the address argument is 0, the current image (which
    contains the call to LIB$LOCK_IMAGE) is locked in the working
    set.

2.148  –  LIB$LOOKUP_KEY

    The Look Up Keyword in Table routine scans a table of keywords
    to find one that matches the keyword or keyword abbreviation
    specified by search-string.

    Format

      LIB$LOOKUP_KEY  search-string ,key-table-array [,key-value]

                      [,keyword-string] [,resultant-length]

2.148.1  –  Returns

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

2.148.2  –  Arguments

 search-string

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

    String for which LIB$LOOKUP_KEY will search in the keyword
    table. The search-string argument is the address of a descriptor
    pointing to this string.

 key-table-array

    OpenVMS usage:unspecified
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Keyword table. The key-table-array argument contains the address
    of an array that is this keyword table.

 key-value

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

    Associated value of the keyword found by LIB$LOOKUP_KEY. The key-
    value argument contains the address of an unsigned longword into
    which LIB$LOOKUP_KEY writes the associated value of the matched
    keyword.

 keyword-string

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

    Full keyword string matched. The keyword-string argument contains
    the address of a character-string descriptor. LIB$LOOKUP_
    KEY writes the complete text of the matched keyword into the
    character string.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of characters copied into the character-string pointed to
    by keyword-string, not counting padding in the case of a fixed-
    length string. The resultant-length argument is the address of an
    unsigned word integer that contains the number of characters in
    the matched keyword that were copied into the character-string.

2.149  –  LIB$LOOKUP_TREE

    The Look Up an Entry in a Balanced Binary Tree routine looks up
    an entry in a balanced binary tree.

    Format

      LIB$LOOKUP_TREE  treehead ,symbol ,user-compare-routine

                       ,new-node

2.149.1  –  Returns

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

2.149.2  –  Arguments

 treehead

    OpenVMS usage:address
    type:         address
    access:       read only
    mechanism:    by reference

    Tree head for the binary tree. The treehead argument is the
    address of an unsigned longword that is this tree head.

 symbol

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       unspecified
    mechanism:    unspecified

    Key to be looked up in the binary tree.

 user-compare-routine

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

    User-supplied compare routine that LIB$LOOKUP_TREE calls to
    compare a symbol with a node. The value returned by the compare
    routine indicates the relationship between the symbol key and the
    current node.

 new-node

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Location where the new symbol was found. The new-node argument
    is the address of an unsigned longword that is the new node
    location.

2.150  –  LIB$LOOKUP_TREE_64

    (Alpha and I64 only.) The Look Up an Entry in a Balanced Binary
    Tree routine looks up an entry in a balanced binary tree.

    Format

      LIB$LOOKUP_TREE_64  treehead ,symbol ,user-compare-routine

                          ,new-node

2.150.1  –  Returns

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

2.150.2  –  Arguments

 treehead

    OpenVMS usage:address
    type:         address
    access:       read only
    mechanism:    by reference

    Tree head for the binary tree. The treehead argument is the
    address of an unsigned quadword that is this tree head.

 symbol

    OpenVMS usage:user_arg
    type:         quadword (unsigned)
    access:       unspecified
    mechanism:    unspecified

    Key to be looked up in the binary tree.

 user-compare-routine

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

    User-supplied compare routine that LIB$LOOKUP_TREE_64 calls to
    compare a symbol with a node. The value returned by the compare
    routine indicates the relationship between the symbol key and the
    current node.

 new-node

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Location where the new symbol was found. The new-node argument
    is the address of an unsigned quadword that is the new node
    location.

2.151  –  LIB$LP_LINES

    The Lines on Each Printer Page routine computes the default
    number of lines on a printer page. This routine can be used by
    native-mode OpenVMS utilities that produce listing files and
    paginate files.

    Format

      LIB$LP_LINES

2.151.1  –  Returns

    OpenVMS usage:longword_signed
    type:         longword integer (signed)
    access:       write only
    mechanism:    by value

    The default number of lines on a physical printer page. If the
    logical name translation or conversion to binary fails, a default
    value of 66 is returned.

2.151.2  –  Arguments

    None.

2.152  –  LIB$MATCHC

    The Match Characters, Return Relative Position routine searches a
    source string for a specified substring and returns an index,
    which is the relative position of the first occurrence of a
    substring in the source string. The relative character positions
    returned by LIB$MATCHC are numbered 1, 2, . . . , n. Thus, zero
    means that the substring was not found.

    Format

      LIB$MATCHC  sub-string ,source-string

2.152.1  –  Returns

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

    The relative position of the first character of the substring if
    found, or zero if not found.

2.152.2  –  Arguments

 sub-string

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

    Substring to be found. The sub-string argument is the address of
    a descriptor pointing to this substring.

 source-string

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

    Source string to be searched by LIB$MATCHC. The source-string
    argument is the address of a descriptor pointing to this source
    string.

2.153  –  LIB$MATCH_COND

    The Match Condition Values routine checks to see if a given
    condition value matches a list of condition values that you
    supply.

    Format

      LIB$MATCH_COND  match-condition-value ,compare-condition-value

                      ,...

2.153.1  –  Returns

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

    A zero, if the input condition value did not match any condition
    value in the list, or i-1,  for a match between the first argument
    and the ith argument.

2.153.2  –  Arguments

 match-condition-value

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

    Condition value to be matched. The match-condition-value argument
    is the address of an unsigned longword that contains this
    condition value.

 compare-condition-value

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

    The condition values to be compared to match-condition-value.
    The compare-condition-value arguments are the addresses of the
    unsigned longwords that contain these condition values.

2.154  –  LIB$MOVC3

    The Move Characters routine makes the VAX MOVC3 instruction
    available as a callable routine. The source item is moved to
    the destination item. Overlap of the source and destination items
    does not affect the result.

    Format

      LIB$MOVC3  word-integer-length ,source ,destination

2.154.1  –  Returns

    None.

2.154.2  –  Arguments

 word-integer-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Number of bytes to be moved from source to destination by
    LIB$MOVC3. The word-integer-length argument is the address of
    an unsigned word that contains this number of bytes. The maximum
    transfer is 65,535 bytes.

 source

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

    Item to be moved. The source argument is the address of this
    item.

 destination

    OpenVMS usage:unspecified
    type:         unspecified
    access:       write only
    mechanism:    by reference

    Item into which source will be moved. The destination argument is
    the address of this item.

2.155  –  LIB$MOVC5

    The Move Characters with Fill routine makes the VAX MOVC5
    instruction available as a callable routine. The source item
    is moved to the destination item. Overlap of the source and
    destination items does not affect the result.

    Format

      LIB$MOVC5  word-integer-source-length ,source [,fill]

                 ,word-integer-destination-length ,destination

2.155.1  –  Returns

    None.

2.155.2  –  Arguments

 word-integer-source-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Number of bytes in the source item. The word-integer-source-
    length argument is the address of an unsigned word that contains
    this number of bytes. The maximum length of source is 65,535
    bytes.

 source

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

    Item to be moved by LIB$MOVC5. The source argument is the address
    of this item. If word-integer-source-length is zero, indicating
    that destination is to be entirely filled by the fill character,
    then source is ignored by LIB$MOVC5.

 fill

    OpenVMS usage:byte_signed
    type:         byte integer (signed)
    access:       read only
    mechanism:    by reference

    Character used to pad source to the length of destination.
    The fill argument is the address of a signed byte integer that
    contains this fill character. If word-integer-destination-length
    is less than or equal to word-integer-source-length, fill is
    unused and may be omitted.

 word-integer-destination-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Length of destination in bytes. The word-integer-destination-
    length argument is the address of an unsigned word that contains
    this number of bytes. The maximum value of word-integer-
    destination-length is 65,535 bytes.

 destination

    OpenVMS usage:unspecified
    type:         unspecified
    access:       write only
    mechanism:    by reference

    Item into which source will be moved. The destination argument is
    the address of this item.

2.156  –  LIB$MOVTC

    The Move Translated Characters routine moves the source
    string, character by character, to the destination string after
    translating each character using the specified translation table.
    LIB$MOVTC makes the VAX MOVTC instruction available as a callable
    routine.

    Format

      LIB$MOVTC  source-string ,fill-character ,translation-table

                 ,destination-string

2.156.1  –  Returns

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

2.156.2  –  Arguments

 source-string

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

    Source string to be translated and moved by LIB$MOVTC. The
    source-string argument is the address of a descriptor pointing
    to this source string.

 fill-character

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

    Fill character used to pad source-string to the length of
    destination-string. The fill-character argument is the address
    of a descriptor pointing to a string. The first character of this
    string is used as the fill character. The length of this string
    is not checked and fill-character is not translated.

 translation-table

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

    Translation table used by LIB$MOVTC. The translation-table
    argument is the address of a descriptor pointing to the
    translation table string. The translation table string is assumed
    to be 256 characters long.

    You can use any one of the translation tables supplied by VSI,
    or you can create your own. Translation tables supplied by VSI
    have names in the format LIB$AB_xxx_yyy, which represent the
    addresses of the 256-byte translation tables and can be accessed
    as external (string) variables. If a particular language cannot
    generate descriptors for external strings, then you must create
    them manually.

 destination-string

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

    Destination string into which LIB$MOVTC writes the translated
    source-string. The destination-string argument is the address of
    a descriptor pointing to this destination string.

2.157  –  LIB$MOVTUC

    The Move Translated Until Character routine moves the source
    string, character by character, to the destination string after
    translating each character using the specified translation table
    until the stop character is encountered. LIB$MOVTUC makes the VAX
    MOVTUC instruction available as a callable routine.

    Format

      LIB$MOVTUC  source-string ,stop-character ,translation-table

                  ,destination-string [,fill-character]

2.157.1  –  Returns

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

    The relative position in the source string of the character that
    is translated to the stop character. Zero is returned if the stop
    character is not found. This value is set to -1 if destination-
    string cannot be allocated.

2.157.2  –  Arguments

 source-string

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

    Source string to be translated and moved by LIB$MOVTUC. The
    source-string argument is the address of a descriptor pointing
    to this source string.

 stop-character

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

    Stop character that causes LIB$MOVTUC to stop translating the
    source string. The stop-character argument is the address of a
    descriptor pointing to a string. The first character of this
    string is used as the stop character. The length of this string
    is not checked. During the translation, LIB$MOVTUC accesses each
    character in the source string and uses it as an index into the
    translation table. If this translated character is the specified
    stop character, translation stops, and stop-character is not
    translated.

 translation-table

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

    Translation table used by LIB$MOVTUC. The translation-table
    argument is the address of a descriptor pointing to the
    translation table string. The translation table string is assumed
    to be 256 characters long.

    You can use any of the translation tables included in the
    Description section of LIB$MOVTC, or you can create your own.
    When using a translation table supplied by VSI, the names LIB$AB_
    xxx_yyy represent the addresses of the 256-byte translation
    tables, and can be accessed as external (string) variables. If
    a particular language cannot generate descriptors for external
    strings, then they must be created manually.

 destination-string

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

    Destination string into which LIB$MOVTUC writes the translated
    source-string. The destination-string argument is the address of
    a descriptor pointing to this destination string.

 fill-character

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

    Character used to pad source-string to the length of destination-
    string. The fill-character argument is the address of a
    descriptor pointing to a string. The first character of this
    string is used as the fill character. The length of this string
    is not checked and fill-character is not translated.

    If the fill character is included, the remainder of the
    destination string (after the stop character) is filled with the
    specified fill character. If it is not included, the remainder of
    the destination string remains unchanged.

2.158  –  LIB$MULTF_DELTA_TIME

    The Multiply Delta Time by an F-Floating Scalar routine
    multiplies a delta time by an F-floating scalar.

    Format

      LIB$MULTF_DELTA_TIME  multiplier ,delta-time

2.158.1  –  Returns

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

2.158.2  –  Arguments

 multiplier

    OpenVMS usage:floating_point
    type:         F_floating
    access:       read only
    mechanism:    by reference

    The value by which LIB$MULTF_DELTA_TIME multiplies the delta
    time. The multiplier argument is the address of an F-floating
    value containing the scalar. If multiplier is negative, the
    absolute value of multiplier is used.

 delta-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by reference

    The delta time to be multiplied. The delta-time argument is
    the address of an unsigned quadword containing the number to
    be multiplied. The initial delta-time argument must be greater
    than 0. After LIB$MULTF_DELTA_TIME performs the multiplication,
    the result is returned to delta-time. (The original delta-time
    value is overwritten.)

2.159  –  LIB$MULTS_DELTA_TIME

    (Alpha and I64 only) The Multiply Delta Time by an IEEE S-
    Floating Scalar routine multiplies a delta time by an IEEE S-
    floating scalar.

    Format

      LIB$MULTS_DELTA_TIME  multiplier ,delta-time

2.159.1  –  Returns

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

2.159.2  –  Arguments

 multiplier

    OpenVMS usage:floating_point
    type:         IEEE S_floating
    access:       read only
    mechanism:    by reference

    The value by which LIB$MULTS_DELTA_TIME multiplies the delta
    time. The multiplier argument is the address of an IEEE S-
    floating value containing the scalar. If multiplier is negative,
    the absolute value of multiplier is used.

 delta-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by reference

    The delta time to be multiplied. The delta-time argument is
    the address of an unsigned quadword containing the number to
    be multiplied. The initial delta-time argument must be greater
    than 0. After LIB$MULTS_DELTA_TIME performs the multiplication,
    the result is returned to delta-time. (The original delta-time
    value is overwritten.)

2.160  –  LIB$MULT_DELTA_TIME

    The Multiply Delta Time by Scalar routine multiplies a delta time
    by a longword integer scalar.

    Format

      LIB$MULT_DELTA_TIME  multiplier ,delta-time

2.160.1  –  Returns

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

2.160.2  –  Arguments

 multiplier

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

    The value by which LIB$MULT_DELTA_TIME multiplies the delta time.
    The multiplier argument is the address of a signed longword
    containing the integer scalar. If multiplier is negative, the
    absolute value of multiplier is used.

 delta-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by reference

    The delta time to be multiplied. The delta-time argument is
    the address of an unsigned quadword containing the number to
    be multiplied. The initial delta-time argument must be greater
    than 0. After LIB$MULT_DELTA_TIME performs the multiplication,
    the result is returned to delta-time. (The original delta-time
    value is overwritten.)

2.161  –  LIB$PARSE_ACCESS_CODE

    The Parse Access Encoded Name String routine parses and
    translates a string of access names into a mask for a particular
    ownership category.

    Format

      LIB$PARSE_ACCESS_CODE  access-string, [access-names,]

                             ownership-category, access-mask,

                             [end-position]

2.161.1  –  Returns

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

2.161.2  –  Arguments

 access-string

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

    The address of a character-string descriptor pointing to a string
    of access names. Each access name is abbreviated to one letter.
    An example of a valid access string is RWE. Access names are
    specific to each of the different object classes. see the VSI
    OpenVMS Guide to System Security for a complete list of all valid
    access names.

 access-names

    OpenVMS usage:access_names
    type:         array [0..31] of quadword string descriptor
    access:       read only
    mechanism:    by reference

    The address of the access name table for the associated object
    class. For example, it is the value returned by the LIB$GET_
    ACCNAM routine in the accnam longword. This parameter is optional
    and defaults to the access name table for the FILE object class.

 ownership-category

    OpenVMS usage:mask_word
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    The address of a word that indicates the ownership category the
    access names refer to:

    Ownership
    Category       Mask Value

    System         0000000000001111
    Owner          0000000011110000
    Group          0000111100000000
    World          1111000000000000

 access-mask

    OpenVMS usage:mask_word
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    The address of a word into which this routine writes the access
    mask. In this mask, a set bit means the access was requested for
    the specified ownership. Note that this is the opposite of the
    standard protection format where a set bit means no access.

 end-position

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       write only
    mechanism:    by reference

    The number of characters from access-string processed by
    LIB$PARSE_ACCESS_CODE. In the case of an error in parsing the
    access string, the offset to the offending location is returned.

2.162  –  LIB$PARSE_SOGW_PROT

    The Parse Protection String routine parses and translates a
    protection string into a protection mask.

    Format

      LIB$PARSE_SOGW_PROT  protection-string, [access-names],

                           protection-mask, ownership-mask,

                           [end-position]

2.162.1  –  Returns

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

2.162.2  –  Arguments

 protection-string

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

    The address of a character-string descriptor pointing to the
    protection string. The string components are:

    o  Ownership name - System,Owner,Group,World. Ownership names can
       be specified in full or truncated to any number of characters.
       Matching is case blind, and spacing is ignored.

    o  Access name - Access names are always abbreviated to one
       letter. For example, access names for files are R (for
       read), W (for write), E (for execute), and D (for delete).
       Any combination can be passed. For example, RWE is a valid
       combination. A null access name specification means no access.

    o  Separators - Access names are separated from ownership names
       by either a colon (:)  or an equal sign (=). The comma (,)  is
       the list separator. A null access name specification means no
       access.

    An example of a valid protection string is:

    SYSTEM=RWED,OWNER:RWED,GROUP,WORLD:R

 access-names

    OpenVMS usage:access_names
    type:         array [0..31] of quadword string descriptor
    access:       read only
    mechanism:    by reference

    The address of the access name table for the associated object
    class. For example, it is the value returned by the LIB$GET_
    ACCNAM routine in the accnam longword. This parameter is optional
    and defaults to the access name table for the FILE object class.

 protection-mask

    OpenVMS usage:protection
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    The address of a word into which this routine writes a 16-bit
    protection mask translation of the protection string. Each
    bit set in the mask indicates no access for the access type it
    represents.

 ownership-mask

    OpenVMS usage:mask_word
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    The address of a word that indicates which ownership names were
    present in the protection string.

    Ownership
    Category       Mask Value

    System         0000000000001111
    Owner          0000000011110000
    Group          0000111100000000
    World          1111000000000000

 end-position

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       write only
    mechanism:    by reference

    The number of characters from protection-string processed by
    LIB$PARSE_SOGW_PROT. In the case of an error in parsing the
    protection string, the offset to the offending location is
    returned.

2.163  –  LIB$PAUSE

    The Pause Program Execution routine suspends program execution
    and returns control to the calling command level.

    Format

      LIB$PAUSE

2.163.1  –  Returns

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

2.163.2  –  Arguments

    None.

2.164  –  LIB$POLYD

    The Evaluate Polynomials routine (D-floating values) allows
    higher-level language users to evaluate D-floating value
    polynomials.

    D-floating values are not supported in full precision in native
    OpenVMS Alpha and I64 programs. They are precise to 56 bits on
    VAX systems, 53 or 56 bits in translated VAX images, and 53 bits
    in native OpenVMS Alpha and I64 programs.

    Format

      LIB$POLYD  polynomial-argument ,degree ,coefficient

                 ,floating-point-result

2.164.1  –  Returns

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

2.164.2  –  Arguments

 polynomial-argument

    OpenVMS usage:floating_point
    type:         D_floating
    access:       read only
    mechanism:    by reference

    The address of a D-floating number that is the argument for the
    polynomial.

 degree

    OpenVMS usage:word_signed
    type:         word integer (signed)
    access:       read only
    mechanism:    by reference

    The address of a signed word integer that is the highest-numbered
    nonzero coefficient to participate in the evaluation.

    If the degree is 0, the result equals C[0]. The range of the
    degree is 0 to 31.

 coefficient

    OpenVMS usage:floating_point
    type:         D_floating
    access:       read only
    mechanism:    by reference, array reference

    The address of an array of D-floating coefficients. The
    coefficient of the highest-order term of the polynomial is the
    lowest-addressed element in the array.

 floating-point-result

    OpenVMS usage:floating_point
    type:         D_floating
    access:       write only
    mechanism:    by reference

    The address of a floating-point number that is the result of
    the calculation. LIB$POLYD writes the address of floating-point-
    result into a D-floating number.

    Intermediate multiplications are carried out using extended
    floating-point fractions (63 bits for POLYD).

2.165  –  LIB$POLYF

    The Evaluate Polynomials routine (F-floating values) allows
    higher-level language users to evaluate F-floating polynomials.

    Format

      LIB$POLYF  polynomial-argument ,degree ,coefficient

                 ,floating-point-result

2.165.1  –  Returns

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

2.165.2  –  Arguments

 polynomial-argument

    OpenVMS usage:floating_point
    type:         F_floating
    access:       read only
    mechanism:    by reference

    Argument for the polynomial. The polynomial-argument argument
    is the address of a floating-point number that contains this
    argument. The polynomial-argument argument is an F-floating
    number.

 degree

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by reference

    Highest-numbered nonzero coefficient to participate in the
    evaluation. The degree argument is the address of a signed word
    integer that contains this highest-numbered coefficient.

    If the degree is 0, the result equals C[0]. The range of the
    degree is 0 to 31.

 coefficient

    OpenVMS usage:floating_point
    type:         F_floating
    access:       read only
    mechanism:    by reference, array reference

    The address of an array of floating-point coefficients. The
    coefficient of the highest-order term of the polynomial is the
    lowest addressed element in the array. The coefficient argument
    is an array of F-floating numbers.

 floating-point-result

    OpenVMS usage:floating_point
    type:         F_floating
    access:       write only
    mechanism:    by reference

    Result of the calculation. The floating-point-result argument is
    the address of a floating-point number that contains this result.
    LIB$POLYF writes the address of floating-point-result into an
    F-floating number.

    Intermediate multiplications are carried out using extended
    floating-point fractions (31 bits for POLYF).

2.166  –  LIB$POLYG

    The Evaluate Polynomials routine (G-floating values) allows
    higher-level language users to evaluate G-floating value
    polynomials.

    Format

      LIB$POLYG  polynomial-argument ,degree ,coefficient

                 ,floating-point-result

2.166.1  –  Returns

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

2.166.2  –  Arguments

 polynomial-argument

    OpenVMS usage:floating_point
    type:         G_floating
    access:       read only
    mechanism:    by reference

    Argument for the polynomial. The polynomial-argument argument
    is the address of a floating-point number that contains this
    argument. The polynomial-argument argument is a G-floating
    number.

 degree

    OpenVMS usage:word_signed
    type:         word integer (signed)
    access:       read only
    mechanism:    by reference

    Highest-numbered nonzero coefficient to participate in the
    evaluation. The degree argument is the address of a signed word
    integer that contains this highest-numbered coefficient.

    If the degree is 0, the result equals C[0]. The range of the
    degree is 0 to 31.

 coefficient

    OpenVMS usage:floating_point
    type:         G_floating
    access:       read only
    mechanism:    by reference, array reference

    Floating-point coefficients. The coefficient argument is
    the address of an array of floating-point coefficients. The
    coefficient of the highest-order term of the polynomial is the
    lowest addressed element in the array. The coefficient argument
    is an array of G-floating numbers.

 floating-point-result

    OpenVMS usage:floating_point
    type:         G_floating
    access:       write only
    mechanism:    by reference

    Result of the calculation. The floating-point-result argument is
    the address of a floating-point number that contains this result.
    LIB$POLYG writes the address of  floating-point-result into a
    G-floating number.

    Intermediate multiplications are carried out using extended
    floating-point fractions (63 bits for POLYG).

2.167  –  LIB$POLYH

    On OpenVMS VAX systems, the Evaluate Polynomials routine (H-
    floating values) allows higher-level language users to evaluate
    H-floating value polynomials.

    This routine is not available to native OpenVMS Alpha and I64
    programs but is available to translated VAX images.

    Format

      LIB$POLYH  polynomial-argument ,degree ,coefficient

                 ,floating-point-result

2.167.1  –  Returns

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

2.167.2  –  Arguments

 polynomial-argument

    OpenVMS usage:floating_point
    type:         H_floating
    access:       read only
    mechanism:    by reference

    Argument for the polynomial. The polynomial-argument argument
    is the address of a floating-point number that contains this
    argument. The polynomial-argument argument is an H-floating
    number.

 degree

    OpenVMS usage:word_signed
    type:         word integer (signed)
    access:       read only
    mechanism:    by reference

    Highest-numbered nonzero coefficient to participate in the
    evaluation. The degree argument is the address of a signed word
    integer that contains this highest-numbered coefficient.

    If the degree is 0, the result equals C[0]. The range of the
    degree is 0 to 31.

 coefficient

    OpenVMS usage:floating_point
    type:         H_floating
    access:       read only
    mechanism:    by reference, array reference

    Floating-point coefficients. The coefficient argument is
    the address of an array of floating-point coefficients. The
    coefficient of the highest-order term of the polynomial is the
    lowest addressed element in the array. The coefficient argument
    is an array of H-floating numbers.

 floating-point-result

    OpenVMS usage:floating_point
    type:         H_floating
    access:       write only
    mechanism:    by reference

    Result of the calculation. The floating-point-result argument is
    the address of a floating-point number that contains this result.
    LIB$POLYH writes the address of floating-point-result into an
    H-floating number.

    Intermediate multiplications are carried out using extended
    floating-point fractions (127 bits for POLYH).

2.168  –  LIB$POLYS

    (Alpha and I64 only.) The Evaluate Polynomials routine (IEEE S-
    floating values) allows higher-level language users to evaluate
    IEEE S-floating polynomials.

    Format

      LIB$POLYS  polynomial-argument ,degree ,coefficient

                 ,floating-point-result

2.168.1  –  Returns

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

2.168.2  –  Arguments

 polynomial-argument

    OpenVMS usage:floating_point
    type:         IEEE S_floating
    access:       read only
    mechanism:    by reference

    Argument for the polynomial. The polynomial-argument argument
    is the address of a floating-point number that contains this
    argument. The polynomial-argument argument is an IEEE S-floating
    number.

 degree

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by reference

    Highest-numbered nonzero coefficient to participate in the
    evaluation. The degree argument is the address of a signed word
    integer that contains this highest-numbered coefficient.

    If the degree is 0, the result equals C[0]. The range of the
    degree is 0 to 31.

 coefficient

    OpenVMS usage:floating_point
    type:         IEEE S_floating
    access:       read only
    mechanism:    by reference, array reference

    The address of an array of floating-point coefficients. The
    coefficient of the highest-order term of the polynomial is the
    lowest addressed element in the array. The coefficient argument
    is an array of IEEE S-floating numbers.

 floating-point-result

    OpenVMS usage:floating_point
    type:         IEEE S_floating
    access:       write only
    mechanism:    by reference

    Result of the calculation. The floating-point-result argument is
    the address of a floating-point number that contains this result.
    LIB$POLYS writes the address of floating-point-result into an
    IEEE S-floating number.

    Intermediate multiplications are carried out using extended
    floating-point fractions (31 bits for POLYS).

2.169  –  LIB$POLYT

    (Alpha and I64 only.) The Evaluate Polynomials routine (IEEE T-
    floating values) allows higher-level language users to evaluate
    IEEE T-floating polynomials.

    Format

      LIB$POLYT  polynomial-argument ,degree ,coefficient

                 ,floating-point-result

2.169.1  –  Returns

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

2.169.2  –  Arguments

 polynomial-argument

    OpenVMS usage:floating_point
    type:         IEEE T_floating
    access:       read only
    mechanism:    by reference

    Argument for the polynomial. The polynomial-argument argument
    is the address of a floating-point number that contains this
    argument. The polynomial-argument argument is an IEEE T-floating
    number.

 degree

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by reference

    Highest-numbered nonzero coefficient to participate in the
    evaluation. The degree argument is the address of a signed word
    integer that contains this highest-numbered coefficient.

    If the degree is 0, the result equals C[0]. The range of the
    degree is 0 to 31.

 coefficient

    OpenVMS usage:floating_point
    type:         IEEE T_floating
    access:       read only
    mechanism:    by reference, array reference

    The address of an array of floating-point coefficients. The
    coefficient of the highest-order term of the polynomial is the
    lowest addressed element in the array. The coefficient argument
    is an array of IEEE T-floating numbers.

 floating-point-result

    OpenVMS usage:floating_point
    type:         IEEE T_floating
    access:       write only
    mechanism:    by reference

    Result of the calculation. The floating-point-result argument is
    the address of a floating-point number that contains this result.
    LIB$POLYT writes the address of floating-point-result into an
    IEEE T-floating number.

    Intermediate multiplications are carried out using extended
    floating-point fractions (31 bits for POLYT).

2.170  –  LIB$PUT_COMMON

    The Put String to Common routine copies the contents of a string
    into the common area. The common area is an area of storage
    that remains defined across multiple image activations in a
    process. Optionally, LIB$PUT_COMMON returns the actual number
    of characters copied. The maximum number of characters that can
    be copied is 252.

    Format

      LIB$PUT_COMMON  source-string [,resultant-length]

2.170.1  –  Returns

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

2.170.2  –  Arguments

 source-string

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

    Source string to be copied to the common area by LIB$PUT_COMMON.
    The source-string argument is the address of a descriptor
    pointing to this source string.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of characters copied by LIB$PUT_COMMON to the common area.
    The resultant-length argument is the address of an unsigned word
    integer that contains this number of characters. LIB$PUT_COMMON
    writes this number into the resultant-length argument.

2.171  –  LIB$PUT_INVO_REGISTERS

    (Alpha and I64 only.) The Put Invocation Registers routine
    modifies specified values in a procedure's invocation context.
    A procedure's invocation context consists of the values stored in
    the integer and floating-point registers as well as the program
    counter and the processor status registers.

    LIB$PUT_INVO_REGISTERS updates internal register save areas with
    the new values. These values are written to the active register
    set by the time control returns to the procedure asociated with
    the specified invocation handle.

    Format

      LIB$PUT_INVO_REGISTERS   invo_handle, invo_context, invo_mask

2.171.1  –  Returns

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

    Status value. A value of 1 indicates success. When the initial
    context represents the bottom of the call chain, a value of 0 is
    returned.

2.171.2  –  Arguments

 invo_handle

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

    Handle for the invocation to be updated.

 invo_context

    OpenVMS usage:invo_context_blk
    type:         structure
    access:       read only
    mechanism:    by reference

    Address of an invocation context block that contains the values
    to be written to the registers.

    Each register that is set in the invo_mask parameter is updated
    using the value found in the corresponding IREG or FREG field of
    the invocation context block. The program counter and processor
    status of the given invocation can also be updated in this way.
    No other fields of the invocation context block are used.

 invo_mask

    OpenVMS usage:mask_quadword
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Address of a 64-bit vector, where each bit corresponds to a
    register field in the passed invo_context. Bits 0 through 29
    correspond to IREG[0] through IREG[29], bit 30 corresponds
    to STACK_POINTER and cannot be changed, bit 31 corresponds to
    PROGRAM_COUNTER, bits 32 through 62 correspond to FREG[0] through
    FREG[30], and bit 63 corresponds to PROCESSOR_STATUS.

2.172  –  LIB$PUT_OUTPUT

    The Put Line to SYS$OUTPUT routine writes a record to the current
    controlling output device, specified by SYS$OUTPUT using the
    OpenVMS RMS $PUT service.

    Format

      LIB$PUT_OUTPUT  message-string

2.172.1  –  Returns

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

2.172.2  –  Argument

 message-string

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

    Message string written to the current controlling output device
    by LIB$PUT_OUTPUT. The message-string argument is the address
    of a descriptor pointing to this message string. RMS handles all
    formatting, so the message does not need to include such ASCII
    formatting instructions as carriage return (CR).

2.173  –  LIB$RADIX_POINT

    The Radix Point Symbol routine returns the system's radix point
    symbol. This symbol is used inside a digit string to separate
    the integer part from the fraction part. This routine works by
    attempting to translate the logical name SYS$RADIX_POINT as a
    process, group, or system logical name.

    Format

      LIB$RADIX_POINT  radix-point-string [,resultant-length]

2.173.1  –  Returns

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

2.173.2  –  Arguments

 radix-point-string

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

    Radix point string. The radix-point-string argument is the
    address of a descriptor pointing to this radix point string.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    The number of characters written into radix-point-string, not
    counting padding in the case of a fixed-length string. The
    resultant-length argument is the address of an unsigned word
    that contains this number.

    If the radix-point-string argument is the address of a fixed-
    length string descriptor, there may not be enough characters
    in the fixed-length string to contain the whole radix point
    string, and the radix point string is truncated. If the radix
    point string is truncated to the size specified in a fixed-
    length string descriptor, resultant-length is set to this size.
    Therefore, resultant-length can always be used by the calling
    program to access a valid substring of radix-point-string.

2.174  –  LIB$REMQHI

    The Remove Entry from Head of Queue routine removes an entry
    from the head of the specified self-relative longword interlocked
    queue. LIB$REMQHI makes the REMQHI instruction available as a
    callable routine.

    Format

      LIB$REMQHI  header ,remque-address [,retry-count]

2.174.1  –  Returns

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

2.174.2  –  Arguments

 header

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       modify
    mechanism:    by reference

    Queue header specifying the queue from which entry will be
    removed. The header argument contains the address of this signed
    aligned quadword integer. The header argument must be initialized
    to zero before first use of the queue; zero means an empty queue.

    On Alpha and I64 systems, the header argument must contain a
    32-bit address. A 64-bit address results in an illegal operand
    exception.

 remque-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Address of the removed entry. The remque-address argument is the
    address of an unsigned longword that contains this address. If
    the queue was empty, remque-address is set to the address of the
    header.

    On Alpha and I64 systems, the remque-address argument must
    contain a 32-bit address. A 64-bit address results in an illegal
    operand exception.

 retry-count

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

    The number of times the operation is to be retried in case
    of secondary-interlock failure of the queue instruction in a
    processor-shared memory application. The retry-count argument is
    the address of a longword that contains the retry count value. A
    value of 1 causes no retries. The default value is 10.

2.175  –  LIB$REMQHIQ

    (Alpha and I64 only.) The Remove Entry from Head of Queue routine
    removes an entry from the head of the specified self-relative
    quadword interlocked queue. LIB$REMQHIQ makes the REMQHIQ
    instruction available as a callable routine.

    Format

      LIB$REMQHIQ  header ,remque-address [,retry-count]

2.175.1  –  Returns

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

2.175.2  –  Arguments

 header

    OpenVMS usage:octaword_signed
    type:         octaword integer (signed)
    access:       modify
    mechanism:    by reference

    Queue header specifying the queue from which entry will be
    removed. The header argument contains the address of this signed
    aligned octaword integer. The header argument must be initialized
    to zero before first use of the queue; zero means an empty queue.

 remque-address

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Address of the removed entry. The remque-address argument is the
    address of an unsigned quadword that contains this address. If
    the queue was empty, remque-address is set to the address of the
    header.

 retry-count

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

    The number of times the operation is to be retried in case
    of secondary-interlock failure of the queue instruction in a
    processor-shared memory application. The retry-count argument is
    the address of a longword that contains the retry count value. A
    value of 1 causes no retries. The default value is 10.

2.176  –  LIB$REMQTI

    The Remove Entry from Tail of Queue routine removes an entry
    from the tail of the specified self-relative longword interlocked
    queue. LIB$REMQTI makes the REMQTI instruction available as a
    callable routine.

    Format

      LIB$REMQTI  header ,remque-address [,retry-count]

2.176.1  –  Returns

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

2.176.2  –  Arguments

 header

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       modify
    mechanism:    by reference

    Queue header specifying the queue from which the entry is to be
    deleted. The header argument contains the address of this signed
    aligned quadword integer. The header argument must be initialized
    to zero before first use of the queue; zero means an empty queue.

    On Alpha and I64 systems, the header argument must contain a 32-
    bit sign-extended address. An illegal operand exception occurs
    for any other form of address.

 remque-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Address of the removed entry. The remque-address argument is the
    address of a longword that contains this address. If the queue
    was empty, remque-address is set to the address of the header.

    On Alpha and I64 systems, the remque-address argument must
    contain a 32-bit sign-extended address. An illegal operand
    exception occurs for any other form of address.

 retry-count

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

    The number of times the operation is to be retried in case
    of secondary-interlock failure of the queue instruction in a
    processor-shared memory application. The retry-count argument is
    the address of a longword that is this retry count value. A value
    of 1 causes no retries. The default value is 10.

2.177  –  LIB$REMQTIQ

    (Alpha and I64 only.) The Remove Entry from Tail of Queue routine
    removes an entry from the tail of the specified self-relative
    quadword interlocked queue. LIB$REMQTIQ makes the REMQTIQ
    instruction available as a callable routine.

    Format

      LIB$REMQTIQ  header ,remque-address [,retry-count]

2.177.1  –  Returns

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

2.177.2  –  Arguments

 header

    OpenVMS usage:octaword_signed
    type:         octaword integer (signed)
    access:       modify
    mechanism:    by reference

    Queue header specifying the queue from which the entry is to be
    deleted. The header argument contains the address of this signed
    aligned octaword integer. The header argument must be initialized
    to zero before first use of the queue; zero means an empty queue.

 remque-address

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Address of the removed entry. The remque-address argument is the
    address of a quadword that contains this address. If the queue
    was empty, remque-address is set to the address of the header.

 retry-count

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

    The number of times the operation is to be retried in case
    of secondary-interlock failure of the queue instruction in a
    processor-shared memory application. The retry-count argument is
    the address of a longword that is this retry count value. A value
    of 1 causes no retries. The default value is 10.

2.178  –  LIB$RENAME_FILE

    The Rename One or More Files routine changes the names of one
    or more files. The specification of the files to be renamed can
    include wildcards.

    LIB$RENAME_FILE is similar in function to the DCL command RENAME.

    Format

      LIB$RENAME_FILE  old-filespec ,new-filespec

                       [,default-filespec] [,related-filespec]

                       [,flags] [,user-success-procedure]

                       [,user-error-procedure]

                       [,user-confirm-procedure]

                       [,user-specified-argument]

                       [,old-resultant-name] [,new-resultant-name]

                       [,file-scan-context]

2.178.1  –  Returns

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

2.178.2  –  Arguments

 old-filespec

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

    File specification of the files to be renamed. The old-filespec
    argument is the address of a descriptor pointing to the old file
    specification. The specification may include wildcards, in which
    case each file that matches the specification will be renamed.
    If running on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set,
    the string must not contain more characters than specified by
    NAML$C_MAXRSS, otherwise the string must not contain more than
    255 characters. Any string class is supported.

 new-filespec

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

    File specification for the new file names. The new-filespec
    argument is the address of a descriptor pointing to the new file
    specification.

    This specification need not be complete; fields omitted or
    specified by using the wildcard character (*)  will be filled in
    from the existing file's name using the same rules as for the DCL
    command RENAME. If running on Alpha or I64 and flag LIB$M_FIL_
    LONG_NAMES is set, the string must not contain more characters
    than specified by NAML$C_MAXRSS, otherwise the string must not
    contain more than 255 characters. Any string class is supported.

 default-filespec

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

    Default file specification of the files to be renamed. The
    default-filespec argument is the address of a descriptor pointing
    to the default file specification.

    This is an optional argument; if omitted, the default is the
    null string. See the OpenVMS Record Management Services Reference
    Manual for information on default file specifications. If running
    on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set, the string
    must not contain more characters than specified by NAML$C_MAXRSS,
    otherwise the string must not contain more than 255 characters.
    Any string class is supported.

 related-filespec

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

    Related file specification of the files to be renamed. The
    related-filespec argument is the address of a descriptor pointing
    to the related file specification. This is an optional argument;
    if omitted, the default is the null string. Any string class is
    supported.

    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. Any
    string class is supported. This is an optional argument.

 flags

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

    Longword of flag bits designating optional behavior. The flags
    argument is the address of an unsigned longword containing the
    flag bits. This is an optional argument; if omitted, the default
    is that all flags are clear.

    The bit number and its meaning are as follows:

    Bit  Symbol             Description

    0    LIB$M_FIL_CUR_VER  If new-filespec does not specify a
                            version number, this flag controls
                            whether a new version number for the
                            output file is to be assigned. If this
                            bit is set, the current version number of
                            the file is used.

                            If this bit is clear, the file is given
                            a version number 1 higher than any
                            previously existing file of the same file
                            name and file type. This is the default
                            action.

 If a file already exists with the same file name, type and version
 number, the error RMS$_FEX is given. This flag is equivalent to the

2.178.2.1    /NONEW_VERSION qualifier of the DCL command RENAME.)

    1    LIB$M_FIL_INH_     Controls whether the renamed file
         SECUR              takes on security attributes of the new
                            location or keeps its existing security
                            attributes. If this bit is clear, the
                            attributes of the renamed file are
                            inherited from the next lower version
                            of the new file name, if any, the new
                            parent directory, or both.

                            If this bit is clear, the file's security
                            attributes are not changed; this is the
                            default action.

                            For more information on file security,
                            see the VSI OpenVMS Guide to System
                            Security. This flag is equivalent to the
                            /INHERIT_SECURITY qualifier of the DCL
                            command RENAME.
    2    LIB$M_FIL_LONG_    (Alpha and I64 only) Controls whether to
         NAMES              accept file specifications greater than
                            255 characters in length. If this bit is
                            set, LIB$RENAME_FILE can process files
                            specifications with a maximum length of
                            NAML$C_MAXRSS characters.

                            If this bit is clear, LIB$RENAME_FILE can
                            process files names with a maximum length
                            of 255 characters.

 user-success-procedure

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

    User-supplied success routine that LIB$RENAME_FILE calls after
    each successful rename.

 user-error-procedure

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

    User-supplied error routine that LIB$RENAME_FILE calls when
    it detects an error. The value returned by the error routine
    determines whether LIB$RENAME_FILE processes more files.

 user-confirm-procedure

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

    User-supplied confirm routine that LIB$RENAME_FILE calls before
    it renames a file. The value returned by the confirm routine
    determines whether or not LIB$RENAME_FILE renames the file.

    The confirm routine can be used to select specific files for
    renaming based on criteria such as expiration date, size, and so
    on.

 user-specified-argument

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

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

 old-resultant-name

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

    String into which LIB$RENAME_FILE copies the old resultant file
    specification of the last file processed. This is an optional
    argument. If present, it is used to store the file specification
    passed to the user-supplied routines instead of a default class
    S, type T string. Any string class is supported.

    If you are specifying one or more of the action routine
    arguments, be sure that the descriptor class used to pass
    resultant-name is the same as the descriptor class required by
    the action routine. 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.

 new-resultant-name

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

    String into which LIB$RENAME_FILE writes the new OpenVMS RMS
    resultant file specification of the last file processed. The new-
    resultant-name argument is the address of a descriptor pointing
    to the new name. This is an optional argument. If present, it is
    used to store the file specification passed to the user-supplied
    routines instead of a class S, type T string. Any string class is
    supported.

    If you are specifying one or more of the action routine
    arguments, be sure that the descriptor class used to pass
    resultant-name is the same as the descriptor class required by
    the action routine. 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.

 file-scan-context

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

    Context for renaming a list of file specifications. The file-
    scan-context is the address of a longword that contains this
    context. You must initialize this longword to zero before the
    first of a series of calls to LIB$RENAME_FILE. LIB$RENAME_
    FILE uses the file scan context to retain the file context for
    multiple input files.

    LIB$FILE_SCAN uses this context to retain multiple input file
    related file context. This is an optional argument; it need only
    be specified if you are using multiple input files, as the DCL
    command RENAME does. You may deallocate the context allocated by
    LIB$FILE_SCAN while processing the LIB$RENAME_FILE requests by
    calling LIB$FILE_SCAN_END after all calls to LIB$RENAME_FILE have
    been completed. See the description of LIB$FILE_SCAN for a more
    detailed description of this argument.

2.179  –  LIB$RESERVE_EF

    The Reserve Event Flag routine allocates a local event flag
    number specified by event-flag-number.

    Format

      LIB$RESERVE_EF  event-flag-number

2.179.1  –  Returns

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

2.179.2  –  Argument

 event-flag-number

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

    Event flag number to be allocated by LIB$RESERVE_EF. The event-
    flag-number argument contains the address of a signed longword
    integer that is this event flag number.

2.180  –  LIB$RESET_VM_ZONE

    The Reset Virtual Memory Zone routine frees all blocks of memory
    that were previously allocated from a zone in the 32-bit virtual
    address space.

    Format

      LIB$RESET_VM_ZONE  zone-id

2.180.1  –  Returns

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

2.180.2  –  Argument

 zone-id

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

    Zone identifier. The zone-id is the address of a longword that
    contains the identifier of a zone created by a previous call to
    LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE.

2.181  –  LIB$RESET_VM_ZONE_64

    (Alpha and I64 only.) The Reset Virtual Memory Zone routine frees
    all blocks of memory that were previously allocated from a zone
    in the 64-bit virtual address space.

    Format

      LIB$RESET_VM_ZONE_64  zone-id

2.181.1  –  Returns

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

2.181.2  –  Argument

 zone-id

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Zone identifier. The zone-id is the address of a quadword that
    contains the identifier of a zone created by a previous call to
    LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64.

2.182  –  LIB$REVERT

    The Revert to the Handler of the Routine Activator routine
    deletes the condition handler established by LIB$ESTABLISH by
    clearing the address pointing to the condition handler from the
    activated routine's stack frame.

    This routine is not available to native OpenVMS Alpha and I64
    programs but is recognized and handled appropriately by most VSI
    high-level language compilers.

    Format

      LIB$REVERT

2.182.1  –  Returns

    OpenVMS usage:address
    type:         address
    access:       write only
    mechanism:    by value

    Previous contents of SF$A_HANDLER (longword 0) of the caller's
    stack frame. This is the address of the condition handler
    previously in effect. If no condition handler was in effect,
    zero is returned.

2.182.2  –  Arguments

    None.

2.183  –  LIB$RUN_PROGRAM

    The Run New Program routine causes the current program to stop
    running and begins execution of another program.

    Format

      LIB$RUN_PROGRAM  program-name

2.183.1  –  Returns

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

2.183.2  –  Argument

 program-name

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

    File name of the program to be run in place of the current
    program. The program-name argument contains the address of a
    descriptor pointing to this file name string.

    The maximum length of the file name is 255 characters. The
    default file type is .EXE.

2.184  –  LIB$SCANC

    The Scan for Characters and Return Relative Position routine is
    used to find a specified set of characters in the source string.
    LIB$SCANC makes the VAX SCANC instruction available as a callable
    routine.

    Format

      LIB$SCANC  source-string ,table-array ,byte-integer-mask

2.184.1  –  Returns

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

    Relative position in the source string of the character that
    terminated the operation, or zero if the terminator character is
    not found. If the source string has a zero length, then a zero is
    returned.

2.184.2  –  Arguments

 source-string

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

    Source string used by LIB$SCANC to index into a table. The
    source-string argument contains the address of a descriptor
    pointing to this source string.

 table-array

    OpenVMS usage:vector_mask_byte
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference, array reference

    Table that LIB$SCANC indexes into and performs a logical AND
    operation with the byte-integer-mask byte. The table-array
    argument contains the address of an unsigned byte array that
    is this table.

 byte-integer-mask

    OpenVMS usage:mask_byte
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Mask on which a logical AND operation is performed with bytes in
    table-array. The byte-integer-mask argument contains the address
    of an unsigned byte that is this mask.

2.185  –  LIB$SCOPY_DXDX

    The Copy Source String Passed by Descriptor to Destination
    routine copies a source string passed by descriptor to a
    destination string.

    Format

      LIB$SCOPY_DXDX  source-string ,destination-string

2.185.1  –  Corresponding JSB Entry Point

      LIB$SCOPY_DXDX6

2.185.2  –  Returns

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

2.185.3  –  Arguments

 source-string

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

    Source string to be copied to the destination string by
    LIB$SCOPY_DXDX. The source-string argument contains the address
    of a descriptor pointing to this source string. The descriptor
    class can be unspecified, fixed-length, decimal string, array,
    noncontiguous array, varying, or dynamic.

 destination-string

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

    Destination string to which the source string is copied. The
    destination-string argument contains the address of a descriptor
    pointing to this destination string.

    The following actions occur depending on the class of the
    destination string's descriptor:

    Descriptor
    Class          Action

    S, Z, SD, A,   Copy the source string. If needed, space-fill or
    NCA            truncate on the right.
    D              If the area specified by the destination
                   descriptor is large enough to contain the source
                   string, copy the source string and set the new
                   length in the destination descriptor. If the area
                   specified is not large enough, return the previous
                   space allocation (if any) and then dynamically
                   allocate the amount of space needed. Copy the
                   source string and set the new length and address
                   in the destination descriptor.
    VS             Copy source string to destination string up to
                   the limit of the descriptor MAXSTRLEN field with
                   no padding. Readjust the current length (CURLEN)
                   field to the actual number of bytes copied.

2.186  –  LIB$SCOPY_R_DX

    The Copy Source String Passed by Reference to Destination
    String routine copies a source string passed by reference to a
    destination string, passed by descriptor.

    Format

      LIB$SCOPY_R_DX  word-integer-source-length ,source-string

                      ,destination-string

2.186.1  –  Corresponding JSB Entry Point

      LIB$SCOPY_R_DX6

2.186.2  –  Returns

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

2.186.3  –  Arguments

 word-integer-source-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Length of the source string in bytes. The  word-integer-source-
    length argument is the address of an unsigned word that contains
    the length of the source string.

 source-string

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

    Source string to be copied to the destination string by
    LIB$SCOPY_R_DX. The source-string argument is the address of
    this source string.

 destination-string

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

    Destination string to which the source string is copied. The
    destination-string argument contains the address of a descriptor
    pointing to this destination string.

2.187  –  LIB$SCOPY_R_DX_64

    (Alpha and I64 only.) The Copy Source String Passed by Reference
    to Destination String routine copies a source string passed by
    reference to a destination string, passed by descriptor.

    Format

      LIB$SCOPY_R_DX_64  quad-integer-source-length ,source-string

                         ,destination-string

2.187.1  –  Returns

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

2.187.2  –  Arguments

 quad-integer-source-length

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Length of the source string in bytes. The quad-integer-source-
    length argument is the address of an unsigned quadword that
    contains the length of the source string.

 source-string

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

    Source string to be copied to the destination string by
    LIB$SCOPY_R_DX_64. The source-string argument is the address
    of this source string.

 destination-string

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

    Destination string to which the source string is copied. The
    destination-string argument contains the address of a descriptor
    pointing to this destination string.

2.188  –  LIB$SET_LOGICAL

    The Set Logical Name routine requests the calling process's
    command language interpreter (CLI) to define or redefine a
    supervisor-mode process logical name. It provides the same
    function as the DCL command DEFINE.

    Format

      LIB$SET_LOGICAL  logical-name [,value-string] [,table]

                       [,attributes] [,item-list]

      Either the item-list or value-string argument must be
      specified. If both item-list and value-string are specified,
      the value-string argument is ignored.

2.188.1  –  Returns

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

2.188.2  –  Arguments

 logical-name

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

    Logical name to be defined or redefined. The logical-name
    argument contains the address of a descriptor pointing to this
    logical name string. The maximum length of a logical name is 255
    characters. Note that logical names are case sensitive.

 value-string

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

    Value to be given to the logical name. The value-string argument
    contains the address of a descriptor pointing to this value
    string. The maximum length of a logical name value is 255
    characters.

    If omitted, an item list must be present to specify the values of
    the logical name.

 table

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

    Name of the table in which to create the logical name. The table
    argument contains the address of a descriptor pointing to the
    logical name table. If no table is specified, LNM$PROCESS is used
    as the default.

 attributes

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

    Logical name or translation attributes. The attributes argument
    is the address of a longword bit mask that contains the logical
    name or translation attributes.

    LNM$M_CONFINE and LNM$M_NO_ALIAS are currently available logical
    name attributes. See the description of the $CRELNM system
    service in the VSI OpenVMS System Services Reference Manual: A-
    GETUAI for definitions of LNM$M_CONFINE and LNM$M_NO_ALIAS. If
    omitted, no special logical name attribute is established.

    If no item-list is specified, the translation attributes
    LNM$M_CONCEALED and LNM$M_TERMINAL may be specified. See
    the description of the ASSIGN command in the VSI OpenVMS DCL
    Dictionary for definitions of these attributes. If an item-list
    is specified, it will contain the translation attributes for each
    equivalence string in the attribute.

 item-list

    OpenVMS usage:item_list_3
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Item list describing the equivalence names for this logical
    name. The item-list argument contains the address of an array
    that contains this item list. If item-list is not specified,
    the logical name will have only one value, as specified in the
    value-string argument. Item codes for use with this item list are
    included in libraries supplied by VSI in module $LNMDEF.

    Either value-string or item-list must be specified. If neither
    is specified, the LIB$_INVARG error is produced. If both value-
    string and item-list are specified, the value-string argument is
    ignored.

    If item-list is specified, only logical name attributes are
    permitted. Translation attributes appear in the item list.

    The item-list argument is needed only when you want to create
    multiple equivalence strings for a single logical name.

2.189  –  LIB$SET_SYMBOL

    The Set Value of CLI Symbol routine requests the calling
    process's command language interpreter (CLI) to define or
    redefine a CLI symbol.

    Format

      LIB$SET_SYMBOL  symbol ,value-string [,table-type-indicator]

2.189.1  –  Returns

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

2.189.2  –  Arguments

 symbol

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

    Name of the symbol to be defined or modified by LIB$SET_SYMBOL.
    The symbol argument is the address of a descriptor pointing to
    this symbol string. If you redefine a previously defined CLI
    symbol, the symbol value is modified to the new value that you
    provide.

    The symbol name is converted to uppercase and trailing blanks are
    removed before use. The symbol argument must begin with a letter,
    a digit, a dollar sign ($),  a hyphen (-), or an underscore (_).
    The maximum length of symbol is 255 characters.

 value-string

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

    Value to be given to the symbol. The value-string argument is the
    address of a descriptor pointing to this value string.

    Trailing blanks are not removed from the value string before use.
    The maximum length of value-string is 1024 characters. Integer
    values are not allowed; LIB$SET_SYMBOL is intended to set string
    CLI symbols, not integer CLI symbols.

 table-type-indicator

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

    Indicator of the table that will contain the defined symbol. The
    table-type-indicator argument is the address of a signed longword
    integer that is this table indicator.

    If omitted, the local symbol table is used. The following are
    possible values for table-type-indicator:

    Symbolic Name        Value  Table Used

    LIB$K_CLI_LOCAL_     1      Local symbol table
    SYM
    LIB$K_CLI_GLOBAL_    2      Global symbol table
    SYM

2.190  –  LIB$SFREE1_DD

    The Free One Dynamic String routine returns the dynamically
    allocated storage for a dynamic string.

    Format

      LIB$SFREE1_DD  descriptor-address

2.190.1  –  Corresponding JSB Entry Point

      LIB$SFREE1_DD6

2.190.2  –  Returns

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

2.190.3  –  Argument

 descriptor-address

    OpenVMS usage:descriptor
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by reference

    Dynamic descriptor specifying the area to be deallocated. The
    descriptor-address argument is the address of an unsigned
    quadword that is this descriptor. The descriptor is assumed to
    be dynamic and its class field is not checked.

2.191  –  LIB$SFREEN_DD

    The Free One or More Dynamic Strings routine returns one or more
    dynamic strings to free storage.

    Format

      LIB$SFREEN_DD  number-of-descriptors ,first-descriptor-array

2.191.1  –  Corresponding JSB Entry Point

      LIB$SFREEN_DD6

2.191.2  –  Returns

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

2.191.3  –  Arguments

 number-of-descriptors

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

    Number of adjacent descriptors freed by LIB$SFREEN_DD. The
    number-of-descriptors argument contains the address of an
    unsigned longword that is this number. The deallocated area is
    returned to free storage.

 first-descriptor-array

    OpenVMS usage:descriptor_array
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by reference, array reference

    First descriptor of an array of descriptors. The first-
    descriptor-array argument contains the address of this first
    descriptor. The descriptors are assumed to be dynamic, and their
    class fields are not checked.

    The descriptor array must contain all 32-bit descriptors or all
    64-bit descriptors. They cannot be mixed.

2.192  –  LIB$SGET1_DD

    The Get One Dynamic String routine allocates dynamic virtual
    memory to the string descriptor you specify.

    Format

      LIB$SGET1_DD  word-integer-length ,descriptor-part

2.192.1  –  Corresponding JSB Entry Point

      LIB$SGET1_DD_R6

2.192.2  –  Returns

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

2.192.3  –  Arguments

 word-integer-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Number of bytes of dynamic virtual memory to be allocated by
    LIB$SGET1_DD. The word-integer-length argument is the address of
    an unsigned word that contains this number. The amount of storage
    allocated may be rounded up automatically.

 descriptor-part

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Descriptor of the dynamic string to which LIB$SGET1_DD allocates
    the dynamic virtual memory. The descriptor-part argument contains
    the address of this descriptor.

    The descriptor-part argument must contain the address of a
    dynamic string descriptor; LIB$SGET1_DD returns an unpredictable
    result if any other type of descriptor is specified by this
    argument.

    The descriptor CLASS field is not checked but is set to dynamic
    (2). The LENGTH field is set to word-integer-length, and the
    POINTER field points to the string area allocated.

2.193  –  LIB$SGET1_DD_64

    (Alpha and I64 only.) The Get One Dynamic String routine
    allocates dynamic virtual memory to the string descriptor you
    specify.

    Format

      LIB$SGET1_DD_64  quad-integer-length ,descriptor-part

2.193.1  –  Returns

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

2.193.2  –  Arguments

 quad-integer-length

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Number of bytes of dynamic virtual memory to be allocated by
    LIB$SGET1_DD_64. The quad-integer-length argument is the address
    of an unsigned quadword that contains this number. The amount of
    storage allocated can be rounded up automatically.

 descriptor-part

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Descriptor of the dynamic string to which LIB$SGET1_DD_64
    allocates the dynamic virtual memory. The descriptor-part
    argument contains the address of this descriptor.

    The descriptor-part argument must contain the address of
    a dynamic string descriptor; LIB$SGET1_DD_64 returns an
    unpredictable result if any other type of descriptor is specified
    by this argument.

    The descriptor CLASS field is not checked but is set to dynamic
    (2). The LENGTH field is set to quad-integer-length, and the
    POINTER field points to the string area allocated.

2.194  –  LIB$SHOW_TIMER

    The Show Accumulated Times and Counts routine returns times and
    counts accumulated since the last call to LIB$INIT_TIMER and
    displays them on SYS$OUTPUT. (LIB$INIT_TIMER must be called prior
    to invoking this routine.) A user-supplied action routine may
    change this default behavior.

    Format

      LIB$SHOW_TIMER  [handle-address] [,code]

                      [,user-action-procedure] [,user-argument-value]

2.194.1  –  Returns

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

2.194.2  –  Arguments

 handle-address

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

    Block of storage containing the value returned by a previous call
    to LIB$INIT_TIMER. The handle-address argument is the address of
    an unsigned longword integer containing that value.

    o  If specified, the pointer must be the same value returned by a
       previous call to LIB$INIT_TIMER.

    o  If omitted, LIB$SHOW_TIMER will use a block of memory
       allocated by LIB$INIT_TIMER.

    o  If handle-address is omitted and LIB$INIT_TIMER has not
       been called previously, the error LIB$_INVARG is returned.
       LIB$INIT_TIMER must be called prior to a call to LIB$SHOW_
       TIMER. Note that the handle-address argument is the same as
       the context argument used in the LIB$INIT_TIMER call.

    LIB$SHOW_TIMER assumes that LIB$INIT_TIMER has been previously
    called, and that the results of that call are stored either in a
    block pointed to by handle-address, or in the memory allocated by
    LIB$INIT_TIMER.

 code

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

    Integer specifying the statistic you want; if it is omitted or
    zero, all five statistics are returned on one line. The code
    argument is the address of a signed longword integer containing
    the statistic code.

    The following values are allowed for the code argument:

    Value Description

    1     Elapsed time
    2     CPU time
    3     Buffered I/O
    4     Direct I/O
    5     Page faults

 user-action-procedure

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

    User-supplied action routine called by LIB$SHOW_TIMER. The
    default action of LIB$SHOW_TIMER is to write the results to
    SYS$OUTPUT. An action routine is useful if you want to write the
    results to a file or, in general, anywhere other than SYS$OUTPUT.

    The action routine returns either a success or failure condition
    value; this status is returned to the calling program as the
    value of LIB$SHOW_TIMER.

 user-argument-value

    OpenVMS usage:user-arg
    type:         longword (unsigned) (on VAX systems)
                              quadword (unsigned) (on Alpha and I64
                  systems)
    access:       read only
    mechanism:    by value

    A value to be passed to the action routine without
    interpretation. If omitted, LIB$SHOW_TIMER passes a zero by value
    to the user routine.

2.195  –  LIB$SHOW_VM

    The Show Virtual Memory Statistics routine returns the statistics
    accumulated from calls to LIB$GET_VM/LIB$FREE_VM and LIB$GET_VM_
    PAGE/LIB$FREE_VM_PAGE.

    Format

      LIB$SHOW_VM  [code] [,user-action-procedure]

                   [,user-specified-argument]

2.195.1  –  Returns

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

2.195.2  –  Arguments

 code

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

    Code specifying any one of the statistics to be written to
    SYS$OUTPUT or passed to an action routine for processing.
    The code argument is the address of a signed longword integer
    containing the statistic code. This is an optional argument. If
    the statistic code is omitted or is zero, statistics for values
    1, 2, and 3 are returned on one line.

    The following values are allowed for the code argument:

    Value Statistic

    0     Statistics for values 1, 2, and 3 are returned.
    1     Number of successful calls to LIB$GET_VM.
    2     Number of successful calls to LIB$FREE_VM.
    3     Number of bytes allocated by LIB$GET_VM but not yet
          deallocated by LIB$FREE_VM.
    4     Statistics for values 5, 6, and 7 are returned.
    5     Number of calls to LIB$GET_VM_PAGE.
    6     Number of calls to LIB$FREE_VM_PAGE.
    7     Number of VAX pages or Alpha pagelets allocated by LIB$GET_
          VM_PAGE but not yet deallocated by LIB$FREE_VM_PAGE.

 user-action-procedure

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

    User-supplied action routine called by LIB$SHOW_VM. By default,
    LIB$SHOW_VM returns statistics to SYS$OUTPUT. An action routine
    is useful when you want to return statistics to a file or, in
    general, to any place other than SYS$OUTPUT. The routine returns
    either a success or failure condition value, which will be
    returned as the value of LIB$SHOW_VM.

 user-specified-argument

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

    A 32-bit value to be passed directly to the action routine
    without interpretation. That is, the contents of the argument
    list entry user-specified-argument are copied to the argument
    list entry for user-action-procedure.

2.196  –  LIB$SHOW_VM_64

    (Alpha and I64 only.) The Show Virtual Memory Statistics routine
    returns the statistics accumulated from calls to LIB$GET_VM_
    64/LIB$FREE_VM_64 and LIB$GET_VM_PAGE_64/LIB$FREE_VM_PAGE_64.

    Format

      LIB$SHOW_VM_64  [code] [,user-action-procedure]

                      [,user-specified-argument]

2.196.1  –  Returns

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

2.196.2  –  Arguments

 code

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Code specifying any one of the statistics to be written to
    SYS$OUTPUT or passed to an action routine for processing.
    The code argument is the address of a signed quadword integer
    containing the statistic code. This is an optional argument. If
    the statistic code is omitted or is zero, statistics for values
    1, 2, and 3 are returned on one line.

    The following values are allowed for the code argument:

    Value Statistic

    0     Statistics for values 1, 2, and 3 are returned.
    1     Number of successful calls to LIB$GET_VM_64.
    2     Number of successful calls to LIB$FREE_VM_64.
    3     Number of bytes allocated by LIB$GET_VM_64 but not yet
          deallocated by LIB$FREE_VM_64.
    4     Statistics for values 5, 6, and 7 are returned.
    5     Number of calls to LIB$GET_VM_PAGE_64.
    6     Number of calls to LIB$FREE_VM_PAGE_64.
    7     Number of Alpha or I64 pagelets allocated by LIB$GET_VM_
          PAGE_64 but not yet deallocated by LIB$FREE_VM_PAGE_64.

 user-action-procedure

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

    User-supplied action routine called by LIB$SHOW_VM_64. By
    default, LIB$SHOW_VM_64 returns statistics to SYS$OUTPUT. An
    action routine is useful when you want to return statistics to
    a file or, in general, to any place other than SYS$OUTPUT. The
    routine returns either a success or failure condition value,
    which will be returned as the value of LIB$SHOW_VM_64.

 user-specified-argument

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

    A 64-bit value to be passed directly to the action routine
    without interpretation. That is, the contents of the argument
    list entry user-specified-argument are copied to the argument
    list entry for user-action-procedure.

2.197  –  LIB$SHOW_VM_ZONE

    The Return Information About a Zone routine returns formatted
    information about a zone in the 32-bit virtual address space,
    detailing such information as the zone's name, characteristics,
    and areas, and then passes the information to the specified or
    default action routine.

    Format

      LIB$SHOW_VM_ZONE  zone-id [,detail-level]

                        [,user-action-procedure] [,user-arg]

2.197.1  –  Returns

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

2.197.2  –  Arguments

 zone-id

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

    Zone identifier. The zone-id argument is the address of an
    unsigned longword containing this identifier. Use zero to
    indicate the 32-bit default zone.

 detail-level

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

    An identifier code specifying the level of detail required
    by the user. The detail-level argument is the address of a
    signed longword containing this code. The default is minimal
    information. The following are valid values for detail-level:

    0    zone-id and name
    1    zone-id, name, algorithm, flags, and size information
    2    zone-id, name, algorithm, flags, size information, cache
         information, and area summary
    3    zone-id, name, algorithm, flags, size information, cache
         information, area summary, and queue validation

 user-action-procedure

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

    Optional user-supplied action routine called by LIB$SHOW_VM_ZONE.
    By default, LIB$SHOW_VM_ZONE prints statistics to SYS$OUTPUT
    by means of LIB$PUT_OUTPUT. An action routine is useful when
    you want to return statistics to a file or, in general, to any
    location other than SYS$OUTPUT. If user-action-procedure fails,
    LIB$SHOW_VM_ZONE terminates and returns a failure code. Success
    codes are ignored.

 user-arg

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

    Optional 32-bit value to be passed directly to the action routine
    without interpretation. That is, the contents of the argument
    list entry user-arg are copied to the argument list entry for
    user-action-procedure.

2.198  –  LIB$SHOW_VM_ZONE_64

    (Alpha and I64 only.) The Return Information About a Zone routine
    returns formatted information about a zone in the 64-bit virtual
    address space, detailing such information as the zone's name,
    characteristics, and areas, and then passes the information to
    the specified or default action routine.

    Format

      LIB$SHOW_VM_ZONE_64  zone-id [,detail-level]

                           [,user-action-procedure] [,user-arg]

2.198.1  –  Returns

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

2.198.2  –  Arguments

 zone-id

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Zone identifier. The zone-id argument is the address of an
    unsigned quadword containing this identifier. Use zero to
    indicate the 64-bit default zone.

 detail-level

    OpenVMS usage:quadword_signed
    type:         quadword (signed)
    access:       read only
    mechanism:    by reference

    An identifier code specifying the level of detail required
    by the user. The detail-level argument is the address of a
    signed quadword containing this code. The default is minimal
    information. The following are valid values for detail-level:

    0    zone-id and name
    1    zone-id, name, algorithm, flags, and size information
    2    zone-id, name, algorithm, flags, size information, cache
         information, and area summary
    3    zone-id, name, algorithm, flags, size information, cache
         information, area summary, and queue validation

 user-action-procedure

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

    Optional user-supplied action routine called by LIB$SHOW_VM_
    ZONE_64. By default, LIB$SHOW_VM_ZONE_64 prints statistics
    to SYS$OUTPUT by means of LIB$PUT_OUTPUT. An action routine
    is useful when you want to return statistics to a file or, in
    general, to any location other than SYS$OUTPUT. If user-action-
    procedure fails, LIB$SHOW_VM_ZONE_64 terminates and returns a
    failure code. Success codes are ignored.

 user-arg

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

    Optional 64-bit value to be passed directly to the action routine
    without interpretation. That is, the contents of the argument
    list entry user-arg are copied to the argument list entry for
    user-action-procedure.

2.199  –  LIB$SIGNAL

    The Signal Exception Condition routine generates a signal that
    indicates that an exception condition has occurred in your
    program. If a condition handler does not take corrective action
    and the condition is severe, then your program will exit.

    Format

      LIB$SIGNAL  condition-value [,condition-argument...]

                  [,condition-value-n [,condition-argument-n...]...]

2.199.1  –  Returns

    None.

2.199.2  –  Arguments

 condition-value

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

    OpenVMS 32-bit condition value. The condition-value argument is
    an unsigned longword that contains this condition value.

    The VSI OpenVMS Programming Concepts Manual explains the format of
    an OpenVMS condition value.

 condition-argument

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       read only
    mechanism:    by value

    As many arguments as are required to process the exception
    specified by condition-value. Note that these arguments are
    also used as FAO (formatted ASCII output) arguments to format
    a message.

    The VSI OpenVMS Programming Concepts Manual explains the message
    format.

 condition-value-n

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

    OpenVMS 32-bit condition value. The optional condition-value-n
    argument is an unsigned longword that contains this condition
    value. The calling routine can specify additional conditions to
    be processed by specifying condition-value-2 through condition-
    value-n, with each condition value followed by any arguments
    required to process the condition specified. However, the total
    number of arguments in the call to LIB$SIGNAL must not exceed
    253.

    The VSI OpenVMS Programming Concepts Manual explains the format of
    an OpenVMS condition value.

 condition-argument-n

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       read only
    mechanism:    by value

    As many arguments as are required to create the message reporting
    the exception specified by condition-value-n.

    The VSI OpenVMS Programming Concepts Manual explains the message
    format.

2.200  –  LIB$SIG_TO_RET

    The Signal Converted to a Return Status routine converts any
    signaled condition value to a value returned as a function. The
    signaled condition is returned to the caller of the user routine
    that established the handler that is calling LIB$SIG_TO_RET. This
    routine may be established as or called from a condition handler.

    Format

      LIB$SIG_TO_RET  signal-arguments ,mechanism-arguments

2.200.1  –  Returns

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

2.200.2  –  Arguments

 signal-arguments

    OpenVMS usage:vector_longword_unsigned
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Signal argument vector. The signal-arguments argument contains
    the address of an array that is this signal argument vector
    stack.

    See the VSI OpenVMS Programming Concepts Manual for a description
    of the signal argument vector.

 mechanism-arguments

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

    Mechanism arguments vector. The mechanism-arguments argument
    contains the address of a structure that is this mechanism
    argument vector stack.

    See the VSI OpenVMS Programming Concepts Manual for a description
    of the mechanism argument vector.

2.201  –  LIB$SIG_TO_STOP

    The Convert a Signaled Condition to a Signaled Stop routine
    converts a signaled condition to a signaled condition that cannot
    be continued.

    Format

      LIB$SIG_TO_STOP  signal-arguments ,mechanism-arguments

2.201.1  –  Returns

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

2.201.2  –  Arguments

 signal-arguments

    OpenVMS usage:vector_longword_unsigned
    type:         unspecified
    access:       modify
    mechanism:    by reference, array reference

    Signal argument vector. The signal-arguments argument contains
    the address of an array that is this signal argument vector
    stack.

    See the VSI OpenVMS Programming Concepts Manual for a description
    of the signal argument vector.

 mechanism-arguments

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

    Mechanism argument vector. The mechanism-arguments argument
    contains the address of a structure that is this mechanism
    argument vector stack.

    See the VSI OpenVMS Programming Concepts Manual for a description
    of the mechanism argument vector.

2.202  –  LIB$SIM_TRAP

    The Simulate Floating Trap routine converts floating faults to
    floating traps. It can be enabled as a condition handler or can
    be called by one.

    This routine is not available to native OpenVMS Alpha or I64
    programs but is available to translated VAX images.

    Format

      LIB$SIM_TRAP  signal-arguments ,mechanism-arguments

2.202.1  –  Returns

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

2.202.2  –  Arguments

 signal-arguments

    OpenVMS usage:vector_longword_unsigned
    type:         unspecified
    access:       modify
    mechanism:    by reference, array reference

    Signal argument vector. The signal-arguments argument contains
    the address of an array that is this signal argument vector
    stack.

    See the VSI OpenVMS Programming Concepts Manual for a description
    of the signal argument vector.

 mechanism-arguments

    OpenVMS usage:vector_longword_unsigned
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Mechanism argument vector. The mechanism-arguments argument
    contains the address of an array that is this mechanism argument
    vector stack.

    See the VSI OpenVMS Programming Concepts Manual for a description
    of the mechanism argument vector.

2.203  –  LIB$SKPC

    The Skip Equal Characters routine compares each character of a
    given string with a given character and returns the relative
    position of the first nonequal character as an index. LIB$SKPC
    makes the VAX SKPC instruction available as a callable routine.

    Format

      LIB$SKPC  character-string ,source-string

2.203.1  –  Returns

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

    The relative position in the source string of the first unequal
    character. LIB$SKPC returns a zero if the source string was of
    zero length or if every character in source-string was equal to
    character-string.

2.203.2  –  Arguments

 character-string

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

    String whose initial character is to be used by LIB$SKPC in the
    comparison. The character-string argument contains the address of
    a descriptor pointing to this string. Only the first character of
    character-string is used, and the length of character-string is
    not checked.

 source-string

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

    String to be searched by LIB$SKPC. The source-string argument
    contains the address of a descriptor pointing to this string.

2.204  –  LIB$SPANC

    The Skip Selected Characters routine is used to skip a specified
    set of characters in the source string. LIB$SPANC makes the VAX
    SPANC instruction available as a callable routine.

    Format

      LIB$SPANC  source-string ,table-array ,byte-integer-mask

2.204.1  –  Returns

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

    The relative position in the source string of the character that
    terminated the operation is returned if such a character is
    found. Otherwise, zero is returned. If the source string has a
    zero length, then a zero is returned.

2.204.2  –  Arguments

 source-string

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

    Source string used by LIB$SPANC to index into table-array. The
    source-string argument contains the address of a descriptor
    pointing to this source string.

 table-array

    OpenVMS usage:vector_mask_byte
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference, array reference

    Table that LIB$SPANC indexes into and performs an AND operation
    with the byte-integer-mask byte. The table-array argument
    contains the address of an unsigned byte array that is this
    table.

 byte-integer-mask

    OpenVMS usage:mask_byte
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Mask that an AND operation is performed with bytes in table-
    array. The byte-integer-mask argument contains the address of an
    unsigned byte that is this mask.

2.205  –  LIB$SPAWN

    The Spawn Subprocess routine requests the command language
    interpreter (CLI) of the calling process to spawn a subprocess
    for executing CLI commands. LIB$SPAWN provides the same function
    as the DCL command SPAWN.

    Format

      LIB$SPAWN  [command-string] [,input-file]

                 [,output-file] [,flags] [,process-name]

                 [,process-id] [,completion-status-address]

                 [,byte-integer-event-flag-num] [,AST-address]

                 [,varying-AST-argument] [,prompt-string] [,cli]

                 [,table]

2.205.1  –  Returns

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

2.205.2  –  Arguments

 command-string

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

    CLI command to be executed by the spawned subprocess. The
    command-string argument is the address of a descriptor pointing
    to this CLI command string. If command-string is omitted,
    commands are taken from the file specified by input-file.

 input-file

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

    Equivalence name to be associated with the logical name SYS$INPUT
    in the logical name table for the subprocess. The input-
    file argument is the address of a descriptor pointing to this
    equivalence string. If input-file is omitted, the default is the
    caller's SYS$INPUT.

 output-file

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

    Equivalence name to be associated with the logical names
    SYS$OUTPUT and SYS$ERROR in the logical name table for the
    subprocess. The output-file argument is the address of a
    descriptor pointing to this equivalence string. If output-file
    is omitted, the default is the caller's SYS$OUTPUT.

 flags

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

    Flag bits that designate optional behavior. The flags argument
    is the address of an unsigned longword that contains these flag
    bits. By default, all flags are clear.

    These flags are defined as follows:

    Bit  Symbol      Meaning

    0    NOWAIT      If this bit is set, the calling process
                     continues executing in parallel with the
                     subprocess. If this bit is clear, the calling
                     process hibernates until the subprocess
                     completes.
    1    NOCLISYM    If this bit is set, the spawned subprocess does
                     not inherit CLI symbols from its caller. If
                     this bit is clear, the subprocess inherits all
                     currently defined CLI symbols. You may want
                     to specify NOCLISYM to help prevent commands
                     redefined by symbol assignments from affecting
                     the spawned commands.
    2    NOLOGNAM    If this bit is set, the spawned subprocess does
                     not inherit process logical names from its
                     caller. If this bit is clear, the subprocess
                     inherits all currently defined process logical
                     names. You may want to specify NOLOGNAM to
                     help prevent commands redefined by logical name
                     assignments from affecting the spawned commands.
    3    NOKEYPAD    If this bit is set, the keypad symbols and state
                     are not passed to the subprocess. If this bit is
                     not set, the keypad settings are passed to the
                     subprocess.
    4    NOTIFY      If this bit is set, a message is broadcast to
                     SYS$OUTPUT when the subprocess completes or
                     aborts. If this bit is not set, no message is
                     broadcast. This bit should not be set unless the
                     NOWAIT bit is also set.
    5    NOCONTROL   If this bit is set, no carriage-return/line-feed
                     is prefixed to any prompt string. If this bit is
                     not set, a carriage-return/line-feed is prefixed
                     to any prompt string specified.
    6    TRUSTED     If this bit is set, it indicates a SPAWN command
                     on behalf of the application. If this bit is
                     not set, it indicates that the SPAWN command
                     originates from user. SPAWN commands originating
                     from users are disallowed in captive accounts
                     (DCL).
    7    AUTHPRIV    If this bit is set, the subprocess inherits the
                     caller's authorized privileges. If this bit is
                     clear, the spawned processes' authorized mask
                     is set equal to the caller's current (active)
                     privilege mask.
    8    SUBSYSTEM   If this bit is set, a spawned process inherits
                     protected subsystem IDs for the duration of
                     LOGINOUT.EXE (used to map the CLI). The IDs
                     will be removed in the process of transferring
                     control to the CLI (as a user mode $RUNDWN is
                     performed). If this bit is clear, LOGINOUT does
                     not execute under the subsystem IDs.

    Bits 9 through 31 are reserved for future expansion and must be
    zero. Symbolic flag names are defined in libraries supplied by VSI
    in module $CLIDEF. They are CLI$M_NOWAIT, CLI$M_NOCLISYM, CLI$M_
    NOLOGNAM, CLI$M_NOKEYPAD, CLI$M_NOTIFY, CLI$M_NOCONTROL, CLI$M_
    TRUSTED, CLI$M_AUTHPRIV, and CLI$M_SUBSYSTEM.

 process-name

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

    Name defined for the subprocess. The process-name argument is the
    address of a descriptor pointing to this name string. If process-
    name is omitted, a unique process name will be generated. If you
    supply a name and it is not unique, LIB$SPAWN will return the
    condition value SS$_DUPLNAM.

    The DCL_CTLFLAGS is a bitmask used to alter default behavior
    for certain commands on a systemwide basis. Currently, only
    the low bit of the bitmask is defined. The low bit controls the
    default process-name assignment for a subprocess created using
    the LIB$SPAWN routine.

    Prior to OpenVMS Version 7.3-1, if no process name was supplied,
    the system constructed a name by appending _n to the username,
    where n was the next available non-duplicate integer for any
    process currently in the system. For example, the first spawned
    process from user SYSTEM would be called SYSTEM_1, the second,
    SYSTEM_2, and so on. The next available number was chosen, as
    soon as a gap was found.

    Beginning in OpenVMS Version 7.3-1, the default constructed
    process name for subprocesses has changed. Instead of
    incrementally searching for the next unique number, a random
    number is chosen to append to the username. Therefore, the first
    processes that are spawned from user SYSTEM might be SYSTEM_154,
    SYSTEM_42, SYSTEM_87, and so on. This procedure results in a
    very high probability of finding a unique number on the first try
    since it is unlikely the same number is already in use.

    However, some applications might rely on the previous method
    of assigning subprocess names. The DCL_CTLFLAGS parameter is
    available to allow you to configure the system as necessary.

    Bit 0 of DCL_CTLFLAGS selects the behavior for assigning default
    subprocess names, as explained in the following:

    o  If clear, the new behavior is used. If the process name is
       not specified, it will be the username with a random number
       suffix. This is the default setting.

    o  If set, the previous behavior is used. If the process name is
       not specified, it will be the username with the next available
       number suffix.

 process-id

    OpenVMS usage:process_id
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Process identification of the spawned subprocess. The process-id
    argument is the address of an unsigned longword that contains
    this process identification value.

    This process identification value is meaningful only if the
    NOWAIT flags bit is set.

 completion-status-address

    OpenVMS usage:address
    type:         address
    access:       read only
    mechanism:    by value

    The final completion status of the subprocess. The completion-
    status-address argument contains the address of the status. The
    system writes the value of the final completion status of the
    subprocess into completion-status-address when the subprocess
    completes. If the subprocess returns a status code of 0, the
    system writes SS$_NORMAL into this address.

    If the NOWAIT flags bit is set, the completion-status-address
    is updated asynchronously when the subprocess completes. Use the
    byte-integer-event-flag-num or AST-address arguments to determine
    when the subprocess has completed. Your program must ensure that
    the address is still valid when the value is written.

 byte-integer-event-flag-num

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    The number of a local event flag to be set when the spawned
    subprocess completes. The byte-integer-event-flag-num argument
    is the address of an unsigned byte that contains this event flag
    number. If byte-integer-event-flag-num is omitted, no event flag
    is set.

    Specifying byte-integer-event-flag-num is meaningful only if the
    NOWAIT flags bit is set.

 AST-address

    OpenVMS usage:procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by value

    Routine to be called by means of an AST when the subprocess
    completes.

    Specifying AST-address is meaningful only if the NOWAIT flags bit
    is set.

 varying-AST-argument

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

    A value to be passed to the AST routine. Typically, the varying-
    AST-argument argument is the address of a block of storage the
    AST routine will use.

    Specifying varying-AST-argument is meaningful only if the NOWAIT
    flags bit is set and if AST-address has been specified.

 prompt-string

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

    Prompt string to use in the subprocess. The prompt-string
    argument is the address of a descriptor pointing to this prompt
    string. If prompt-string is omitted, the subprocess uses the same
    prompt string that the parent process uses.

 cli

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

    File specification for the command language interpreter (CLI)
    to be run in the subprocess. The cli argument is the address of
    this file specification string's descriptor. The CLI specified
    must reside in SYS$SYSTEM with a file type of .EXE, and it must
    be installed. No directory or file type may be specified. The cli
    argument must be specified in uppercase characters.

    If cli is omitted, the subprocess uses the same CLI as the
    parent process. If cli is specified, no context is copied to
    the subprocess.

 table

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

    File specification for the command tables to be used by the
    spawned process. The table argument is the address of this file
    specification string's descriptor. The table specified must
    reside in SYS$SHARE with a file type of .EXE, and it must be
    installed.

    If table is omitted, the subprocess uses the same table as the
    parent process.

2.206  –  LIB$STAT_TIMER

    The Statistics, Return Accumulated Times and Counts routine
    returns to its caller one of five available statistics
    accumulated since the last call to LIB$INIT_TIMER. Unlike
    LIB$SHOW_TIMER, which formats the values for output, LIB$STAT_
    TIMER returns the value as an unsigned longword or quadword.

    Format

      LIB$STAT_TIMER  code ,value-argument [,handle-address]

2.206.1  –  Returns

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

2.206.2  –  Arguments

 code

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

    The address of a signed longword integer that contains a code to
    specify the statistic to be returned. The code specification must
    be an integer from 1 to 5.

    The following values are allowed for code:

    Value Statistic Returned

    1     Elapsed real time (quadword, in system time format)
    2     Elapsed CPU time (longword, in 10 millisecond increments)
    3     Count of buffered I/O operations (longword)
    4     Count of direct I/O operations (longword)
    5     Count of page faults (longword)

 value-argument

    OpenVMS usage:user_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    The statistic returned by LIB$STAT_TIMER. The value-argument
    argument contains the address of a longword or quadword that
    is this statistic. All statistics are longword integers except
    elapsed real time, which is a quadword.

    See the VSI OpenVMS System Services Reference Manual for more
    details on the system time format.

 handle-address

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

    Pointer to a block of storage. The optional handle-address
    argument contains the address of an unsigned longword that is
    this pointer.

    If handle-address is specified, LIB$STAT_TIMER assumes that
    LIB$INIT_TIMER has been called with the same value of handle-
    address. Handle-address is an optional argument. If it is not
    specified, LIB$STAT_TIMER uses internal storage.

2.207  –  LIB$STAT_VM

    The Return Virtual Memory Statistics routine returns to its
    caller one of six statistics available from calls to LIB$GET_
    VM/LIB$FREE_VM and LIB$GET_VM_PAGE/LIB$FREE_VM_PAGE. Unlike
    LIB$SHOW_VM, which formats the values for output and displays
    them on SYS$OUTPUT, LIB$STAT_VM returns the statistic in the
    value-argument argument. Only one of the statistics is returned
    by each call to LIB$STAT_VM.

    Format

      LIB$STAT_VM  code ,value-argument

2.207.1  –  Returns

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

2.207.2  –  Arguments

 code

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

    Code specifying which statistic is to be returned. The code
    argument contains the address of a signed longword integer that
    is this code.

    Code  Statistic

    1     Number of successful calls to LIB$GET_VM
    2     Number of successful calls to LIB$FREE_VM
    3     Number of bytes allocated by LIB$GET_VM but not yet
          deallocated by LIB$FREE_VM
    5     Number of calls to LIB$GET_VM_PAGE
    6     Number of calls to LIB$FREE_VM_PAGE
    7     Number of VAX pages or Alpha pagelets allocated by LIB$GET_
          VM_PAGE but not yet deallocated by LIB$FREE_VM_PAGE

    Note that it is invalid to omit code or to give a code of 0 or 4.

 value-argument

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Value of the statistic returned by LIB$STAT_VM. The value-
    argument argument contains the address of an unsigned longword
    integer that is this value.

2.208  –  LIB$STAT_VM_64

    (Alpha and I64 only.) The Return Virtual Memory Statistics
    routine returns to its caller one of six statistics available
    from calls to LIB$GET_VM_64 and LIB$FREE_VM_64, as well as
    LIB$GET_VM_PAGE_64 and LIB$FREE_VM_PAGE_64. Unlike LIB$SHOW_
    VM_64, which formats the values for output and displays them on
    SYS$OUTPUT, LIB$STAT_VM_64 returns the statistic in the value-
    argument argument. Only one of the statistics is returned by each
    call to LIB$STAT_VM_64.

    Format

      LIB$STAT_VM_64  code ,value-argument

2.208.1  –  Returns

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

2.208.2  –  Arguments

 code

    OpenVMS usage:quadword_signed
    type:         quadword integer (signed)
    access:       read only
    mechanism:    by reference

    Code specifying which statistic is to be returned. The code
    argument contains the address of a signed quadword integer that
    is this code.

    Code  Statistic

    1     Number of successful calls to LIB$GET_VM_64
    2     Number of successful calls to LIB$FREE_VM_64
    3     Number of bytes allocated by LIB$GET_VM_64 but not yet
          deallocated by LIB$FREE_VM_64
    5     Number of calls to LIB$GET_VM_PAGE_64
    6     Number of calls to LIB$FREE_VM_PAGE_64
    7     Number of Alpha or I64 pagelets allocated by LIB$GET_VM_
          PAGE_64 but not yet deallocated by LIB$FREE_VM_PAGE_64

    Note that it is invalid to omit code or to give a code of 0 or 4.

 value-argument

    OpenVMS usage:user_arg
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    Value of the statistic returned by LIB$STAT_VM_64. The value-
    argument argument contains the address of an unsigned quadword
    integer that is this value.

2.209  –  LIB$STOP

    The Stop Execution and Signal the Condition routine generates a
    signal that indicates that an exception condition has occurred in
    your program. Exception conditions signaled by LIB$STOP cannot be
    continued from the point of the signal.

    Format

      LIB$STOP  condition-value [,number-of-arguments]

                [,FAO-argument...]

2.209.1  –  Returns

    LIB$STOP generates a signal and stops execution of the calling
    program. No condition values are returned.

2.209.2  –  Arguments

 condition-value

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

    OpenVMS 32-bit condition value. The condition-value argument is
    an unsigned longword that contains this condition value.

    The VSI OpenVMS Programming Concepts Manual explains the format of
    a condition value.

 number-of-arguments

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

    Number of FAO arguments associated with condition-value. The
    optional number-of-arguments argument is a signed longword
    integer that contains this number. If omitted or specified as
    zero, no FAO arguments follow.

 FAO-argument

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       read only
    mechanism:    by value

    Optional FAO (formatted ASCII output) argument that is associated
    with the specified condition value.

    The VSI OpenVMS Programming Concepts Manual explains the message
    format.

2.210  –  LIB$SUBX

    The Multiple-Precision Binary Subtraction routine performs
    subtraction on signed two's complement integers of arbitrary
    length.

    Format

      LIB$SUBX  minuend-array ,subtrahend-array ,difference-array

                [,array-length]

2.210.1  –  Returns

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

2.210.2  –  Arguments

 minuend-array

    OpenVMS usage:vector_longword_signed
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Minuend; a multiple-precision, signed two's complement integer.
    The minuend-array argument is the address of an array of signed
    longword integers that contains the minuend.

 subtrahend-array

    OpenVMS usage:vector_longword_signed
    type:         unspecified
    access:       read only
    mechanism:    by reference, array reference

    Subtrahend; a multiple-precision, signed two's complement
    integer. The subtrahend-array argument is the address of an array
    of signed longword integers that contains the subtrahend.

 difference-array

    OpenVMS usage:vector_longword_signed
    type:         unspecified
    access:       write only
    mechanism:    by reference, array reference

    Difference; a multiple-precision, signed two's complement integer
    result. The difference-array argument is the address of an array
    of signed longword integers that contains the difference.

 array-length

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

    Length in longwords of the arrays to be operated on by LIB$SUBX.
    The array-length argument contains the address of a signed
    longword integer that is this length. The array-length argument
    must not be negative. The default length is 2 units.

2.211  –  LIB$SUB_TIMES

    The Subtract Two Quadword Times routine subtracts two OpenVMS
    internal-time-format times.

    Format

      LIB$SUB_TIMES  time1 ,time2 ,resultant-time

2.211.1  –  Returns

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

2.211.2  –  Arguments

 time1

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    First time, from which LIB$SUB_TIMES subtracts the second
    time. The time1 argument is the address of an unsigned quadword
    containing this time. The time1 argument must represent a later
    or equal time or a longer or equal time interval than time2. The
    time1 argument may be either absolute time or delta time as long
    as time2 is of the same type. If time1 and time2 are of different
    types, time1 must be the absolute time.

 time2

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Second time, which LIB$SUB_TIMES subtracts from the first time.
    The time2 argument is the address of an unsigned quadword
    containing this time. The time2 argument must represent an
    earlier or equal time or a shorter or equal time interval than
    time1. The time2 argument may be either absolute time or delta
    time as long as time1 is of the same type. If time2 and time1 are
    of different types, time2 must be the delta time.

 resultant-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference

    The result of subtracting time2 from time1. The resultant-time
    argument is the address of an unsigned quadword containing the
    result. If both time1 and time2 are delta times, then resultant-
    time is a delta time. If both time1 and time2 are absolute times,
    then resultant-time is a delta time. If time1 is an absolute time
    and time2 is a delta time, then resultant-time is an absolute
    time.

2.212  –  LIB$SYS_ASCTIM

    The Invoke $ASCTIM to Convert Binary Time to ASCII String routine
    calls the system service $ASCTIM to convert a binary date and
    time value, returning the ASCII string using the semantics of the
    caller's string.

    Format

      LIB$SYS_ASCTIM  [resultant-length] ,time-string [,user-time]

                      [,flags]

2.212.1  –  Returns

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

2.212.2  –  Arguments

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of bytes written into time-string, not counting padding in
    the case of a fixed-length string. The resultant-length argument
    contains the address of an unsigned word integer that is this
    number.

    If the input string is truncated to the size specified in the
    time-string descriptor, resultant-length is set to this size.
    Therefore, resultant-length can always be used by the calling
    program to access a valid substring of time-string.

 time-string

    OpenVMS usage:time_name
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which LIB$SYS_ASCTIM writes the ASCII
    time string. The time-string argument contains the address of a
    descriptor pointing to the destination string.

 user-time

    OpenVMS usage:date_time
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Value that LIB$SYS_ASCTIM converts to ASCII string form. The
    user-time argument contains the address of a signed quadword
    integer that is this value.

    If 0 or no address is specified, the current system date and time
    are returned. A positive value represents an absolute time. A
    negative value represents a delta time. Delta times must be less
    than 10,000 days.

 flags

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

    Conversion indicator specifying which date and time fields
    LIB$SYS_ASCTIM should return. The flags argument is the address
    of an unsigned bit mask that contains this conversion indicator.

    A value of 1 causes only the hour, minute, second, and hundredths
    of a second to be returned, depending on the length of the
    buffer. A value of 0 (the default) causes the full date and time
    to be returned, depending on the length of the buffer.

    The results of specifying some possible combinations for the
    values of the flags and time-string arguments are shown below:

               Time-
    Time       String     Flags
    Value      Length     Value   Information Returned

    Absolute   23         0       Date and time
    Absolute   12         0       Date
    Absolute   11         1       Time
    Delta      16         0       Days and time
    Delta      11         1       Time

    The flags argument is passed to LIB$SYS_ASCTIM by reference and
    is changed to value for use by $ASCTIM.

2.213  –  LIB$SYS_FAO

    The Invoke $FAO System Service to Format Output routine calls
    the $FAO system service, returning a string in the semantics
    you provide. If called with other than a fixed-length string
    for output, the length of the resultant string is limited to 256
    bytes and truncation occurs.

    Format

      LIB$SYS_FAO  character-string, [resultant-length]

                   ,resultant-string [,directive-argument

                   ,...]

2.213.1  –  Returns

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

2.213.2  –  Arguments

 character-string

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

    ASCII control string, consisting of the fixed text of the output
    string and FAO directives. The character-string argument contains
    the address of a descriptor pointing to this control string.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the output string. The resultant-length argument
    contains the address of an unsigned word integer that is this
    length.

 resultant-string

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

    Fully formatted output string returned by LIB$SYS_FAO. The
    resultant-string argument contains the address of a descriptor
    pointing to this output string.

 directive-argument

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       read only
    mechanism:    unspecified

    Directive argument contained in longwords. Depending on the
    directive, a directive-argument argument can be a value to
    be converted, the address of the string to be inserted, or a
    length or argument count. The passing mechanism for each of these
    arguments should be the one expected by the $FAO system service.

2.214  –  LIB$SYS_FAOL

    The Invoke $FAOL System Service to Format Output routine calls
    the $FAOL system service, returning the string in the semantics
    you provide. If called with other than a fixed-length string
    for output, the length of the resultant string is limited to 256
    bytes and truncation occurs.

    Format

      LIB$SYS_FAOL  character-string [,resultant-length]

                    ,resultant-string ,directive-argument-address

2.214.1  –  Returns

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

2.214.2  –  Arguments

 character-string

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

    ASCII control string, consisting of the fixed text of the output
    string and FAO directives. The character-string argument contains
    the address of a descriptor pointing to this control string.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the output string. The resultant-length argument
    contains the address of an unsigned word integer that is this
    length.

 resultant-string

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

    Fully formatted output string returned by LIB$SYS_FAOL. The
    resultant-string argument contains the address of a descriptor
    pointing to this output string.

 directive-argument-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read only
    mechanism:    unspecified

    Directive arguments. The directive-argument-address arguments are
    contained in an array of unsigned longword directive arguments.
    Depending on the directive, a directive-argument-address argument
    can be a value to be converted, the address of the string to be
    inserted, or a length or argument count. The passing mechanism
    for each of these arguments should be the one expected by the
    $FAOL system service.

2.215  –  LIB$SYS_FAOL_64

    (Alpha and I64 only.) The Invoke $FAOL_64 System Service to
    Format Output routine calls the $FAOL_64 system service,
    returning the string in the semantics you provide. If called with
    other than a fixed-length string for output, the length of the
    resultant string is limited to 256 bytes and truncation occurs.

    Format

      LIB$SYS_FAOL_64  character-string [,resultant-length]

                       ,resultant-string ,directive-argument-address

2.215.1  –  Returns

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

2.215.2  –  Arguments

 character-string

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

    ASCII control string, consisting of the fixed text of the output
    string and FAO directives. The character-string argument contains
    the address of a descriptor pointing to this control string.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the output string. The resultant-length argument
    contains the address of an unsigned word integer that is this
    length.

 resultant-string

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

    Fully formatted output string returned by LIB$SYS_FAOL_64. The
    resultant-string argument contains the address of a descriptor
    pointing to this output string.

 directive-argument-address

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       read only
    mechanism:    unspecified

    Directive arguments. The directive-argument-address arguments are
    contained in an array of unsigned quadword directive arguments.
    Depending on the directive, a directive-argument-address argument
    can be a value to be converted, the address of the string to be
    inserted, or a length or argument count. The passing mechanism
    for each of these arguments should be the one expected by the
    $FAOL_64 system service.

2.216  –  LIB$SYS_GETMSG

    The Invoke $GETMSG System Service to Get Message Text routine
    calls the system service $GETMSG and returns a message string
    into destination-string using the semantics of the caller's
    string.

    Format

      LIB$SYS_GETMSG  message-id [,message-length]

                      ,destination-string [,flags]

                      [,unsigned-resultant-array]

2.216.1  –  Returns

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

2.216.2  –  Arguments

 message-id

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

    Message identification to be retrieved by LIB$SYS_GETMSG. The
    message-id argument contains the address of an unsigned longword
    integer that is this message identification.

 message-length

    OpenVMS usage:word_unsigned
    type:         word integer (unsigned)
    access:       write only
    mechanism:    by reference

    Number of characters written into destination-string, not
    counting padding in the case of a fixed-length string. The
    message-length argument contains the address of an unsigned word
    integer that is this number.

    If the input string is truncated to the size specified in the
    destination-string descriptor, message-length is set to this
    size. Therefore, message-length can always be used by the calling
    program to access a valid substring of destination-string.

 destination-string

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

    Destination string. The destination-string argument contains the
    address of a descriptor pointing to this destination string.
    LIB$SYS_GETMSG writes the message that has been returned by
    $GETMSG into destination-string.

 flags

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

    Four flag bits for message content. The flags argument is the
    address of an unsigned longword that contains these flag bits.
    The default value is a longword with bits 0 through 3 set to 1.
    The flags argument is passed to LIB$SYS_GETMSG by reference and
    changed to value for use by $GETMSG.

    The following table lists the bit numbers, their values, and
    corresponding descriptions:

    Bit  Value Description

    0    1     Include text of message.
         0     Do not include text of message.
    1    1     Include message identifier.
         0     Do not include message identifier.
    2    1     Include severity indicator.
         0     Do not include severity indicator.
    3    1     Include facility name.
         0     Do not include facility name.

 unsigned-resultant-array

    OpenVMS usage:unspecified
    type:         unspecified
    access:       write only
    mechanism:    by reference, array reference

    A 4-byte array to receive message-specific information. The
    unsigned-resultant-array argument contains the address of this
    array.

    The contents of this 4-byte array are as follows:

    Byte Contents

    0    Reserved
    1    Count of FAO arguments
    2    User value
    3    Reserved

2.217  –  LIB$TPARSE

    The Table-Driven Finite-State Parser routine is a general-
    purpose, table-driven parser implemented as a finite-state
    automaton, with extensions that make it suitable for a wide
    range of applications. It parses a string and returns a message
    indicating whether or not the input string is valid.

    LIB$T[ABLE_]PARSE is called with the address of an argument
    block, the address of a state table, and the address of a keyword
    table. The input string is specified as part of the argument
    block.

    The LIB$ facility supports the following two versions of the
    Table-Driven Finite-State Parser:

    LIB$TPARSE       Available on VAX systems.
                     LIB$TPARSE is available on Alpha and I64
                     systems in translated form. In this form, it
                     is applicable to translated VAX images only.
    LIB$TABLE_PARSE  Available on VAX, Alpha, and I64 systems.

    LIB$TPARSE and LIB$TABLE_PARSE differ mainly in the way they pass
    arguments to action routines.

    The term LIB$T[ABLE_]PARSE is used here to describe concepts that
    apply to both LIB$TPARSE and LIB$TABLE_PARSE.

    Format

      LIB$TPARSE/LIB$TABLE_PARSE  argument-block ,state-table

                                  ,key-table

2.217.1  –  Returns

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

2.217.2  –  Arguments

 argument-block

    OpenVMS usage:unspecified
    type:         unspecified
    access:       modify
    mechanism:    by reference

    LIB$T[ABLE_]PARSE argument block. The argument-block argument
    contains the address of this argument block.

    The LIB$T[ABLE_]PARSE argument block contains information about
    the state of the parse operation. It is a means of communication
    between LIB$T[ABLE_]PARSE and the user's program. It is passed as
    an argument to all action routines.

    You must declare and initialize the argument block.

    LIB$T[ABLE_]PARSE supports the following argument blocks:

    o  A 32-bit argument block that accommodates longword addresses,
       values, and input tokens on VAX, Alpha, and I64 systems.

       On Alpha and I64 systems, this argument block also
       accommodates a numeric token whose binary representation is
       less than or equal to 2**64.

    o  A 64-bit argument block that accommodates quadword addresses,
       values, and input tokens on Alpha and I64 systems.

 state-table

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

    Starting state in the state table. The state-table argument is
    the address of this starting state. Usually, the name appearing
    as the first argument of the $INIT_STATE macro is used.

    You must define the state table for your parser.
    LIB$T[ABLE_]PARSE provides macros in the MACRO and BLISS
    languages for this purpose.

 key-table

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

    Keyword table. The key-table argument is the address of this
    keyword table. This name must be the same as that which appears
    as the second argument of the $INIT_STATE macro.

    You must only assign a name to the keyword table. The
    LIB$T[ABLE_]PARSE macros allocate and define the table.

2.218  –  LIB$TABLE_PARSE

    The Table-Driven Finite-State Parser routine is a general-
    purpose, table-driven parser implemented as a finite-state
    automaton, with extensions that make it suitable for a wide
    range of applications. It parses a string and returns a message
    indicating whether or not the input string is valid.

    LIB$T[ABLE_]PARSE is called with the address of an argument
    block, the address of a state table, and the address of a keyword
    table. The input string is specified as part of the argument
    block.

    The LIB$ facility supports the following two versions of the
    Table-Driven Finite-State Parser:

    LIB$TPARSE       Available on VAX systems.
                     LIB$TPARSE is available on Alpha and I64
                     systems in translated form. In this form, it
                     is applicable to translated VAX images only.
    LIB$TABLE_PARSE  Available on VAX, Alpha, and I64 systems.

    LIB$TPARSE and LIB$TABLE_PARSE differ mainly in the way they pass
    arguments to action routines.

    The term LIB$T[ABLE_]PARSE is used here to describe concepts that
    apply to both LIB$TPARSE and LIB$TABLE_PARSE.

    Format

      LIB$TPARSE/LIB$TABLE_PARSE  argument-block ,state-table

                                  ,key-table

2.218.1  –  Returns

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

2.218.2  –  Arguments

 argument-block

    OpenVMS usage:unspecified
    type:         unspecified
    access:       modify
    mechanism:    by reference

    LIB$T[ABLE_]PARSE argument block. The argument-block argument
    contains the address of this argument block.

    The LIB$T[ABLE_]PARSE argument block contains information about
    the state of the parse operation. It is a means of communication
    between LIB$T[ABLE_]PARSE and the user's program. It is passed as
    an argument to all action routines.

    You must declare and initialize the argument block.

    LIB$T[ABLE_]PARSE supports the following argument blocks:

    o  A 32-bit argument block that accommodates longword addresses,
       values, and input tokens on VAX, Alpha, and I64 systems.

       On Alpha and I64 systems, this argument block also
       accommodates a numeric token whose binary representation is
       less than or equal to 2**64.

    o  A 64-bit argument block that accommodates quadword addresses,
       values, and input tokens on Alpha and I64 systems.

 state-table

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

    Starting state in the state table. The state-table argument is
    the address of this starting state. Usually, the name appearing
    as the first argument of the $INIT_STATE macro is used.

    You must define the state table for your parser.
    LIB$T[ABLE_]PARSE provides macros in the MACRO and BLISS
    languages for this purpose.

 key-table

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

    Keyword table. The key-table argument is the address of this
    keyword table. This name must be the same as that which appears
    as the second argument of the $INIT_STATE macro.

    You must only assign a name to the keyword table. The
    LIB$T[ABLE_]PARSE macros allocate and define the table.

2.219  –  LIB$TRAVERSE_TREE

    The Traverse a Balanced Binary Tree routine calls an action
    routine for each node in a binary tree.

    Format

      LIB$TRAVERSE_TREE  treehead ,user-action-procedure

                         [,user-data-address]

2.219.1  –  Returns

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

2.219.2  –  Arguments

 treehead

    OpenVMS usage:address
    type:         address
    access:       read only
    mechanism:    by reference

    Tree head of the binary tree. The treehead argument is the
    address of an unsigned longword that is the tree head in the
    binary tree traversal.

 user-action-procedure

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

    User-supplied action routine called by LIB$TRAVERSE_TREE for each
    node in the tree. The user-action-procedure argument must return
    a success status for LIB$TRAVERSE_TREE to continue traversal.

 user-data-address

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

    User data that LIB$TRAVERSE_TREE passes to your action routine.
    The user-data-address argument contains the address of this user
    data. This is an optional argument; the default value is 0.

2.220  –  LIB$TRAVERSE_TREE_64

    (Alpha and I64 only.) The Traverse a Balanced Binary Tree routine
    calls an action routine for each node in a binary tree.

    Format

      LIB$TRAVERSE_TREE_64  treehead ,user-action-procedure

                            [,user-data-address]

2.220.1  –  Returns

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

2.220.2  –  Arguments

 treehead

    OpenVMS usage:address
    type:         address
    access:       read only
    mechanism:    by reference

    Tree head of the binary tree. The treehead argument is the
    address of an unsigned quadword that is the tree head in the
    binary tree traversal.

 user-action-procedure

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

    User-supplied action routine called by LIB$TRAVERSE_TREE_64 for
    each node in the tree. The user-action-procedure argument must
    return a success status for LIB$TRAVERSE_TREE_64 to continue
    traversal.

 user-data-address

    OpenVMS usage:user_arg
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    User data that LIB$TRAVERSE_TREE_64 passes to your action
    routine. The user-data-address argument contains the address of
    this user data. This is an optional argument; the default value
    is 0.

2.221  –  LIB$TRA_ASC_EBC

    The Translate ASCII to EBCDIC routine translates an ASCII string
    to an EBCDIC string.

    Format

      LIB$TRA_ASC_EBC  source-string ,byte-integer-dest-string

2.221.1  –  Returns

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

2.221.2  –  Arguments

 source-string

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

    Source string (ASCII) to be translated by LIB$TRA_ASC_EBC. The
    source-string argument contains the address of a descriptor
    pointing to this source string.

 byte-integer-dest-string

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

    Destination string (EBCDIC). The byte-integer-dest-string
    argument contains the address of a descriptor pointing to this
    destination string.

2.222  –  LIB$TRA_EBC_ASC

    The Translate EBCDIC to ASCII routine translates an EBCDIC string
    to an ASCII string.

    Format

      LIB$TRA_EBC_ASC  byte-integer-source-string ,destination-string

2.222.1  –  Returns

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

2.222.2  –  Arguments

 byte-integer-source-string

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

    String (EBCDIC) to be translated by LIB$TRA_EBC_ASC. The
    byte-integer-source-string argument contains the address of a
    descriptor pointing to this source string.

 destination-string

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

    Destination string (ASCII). The destination-string argument
    contains the address of the descriptor of this destination
    string.

    The LIB$TRA_EBC_ASC routine uses the EBCDIC to ASCII translation
    table, LIB$AB_EBC_ASC.

2.223  –  LIB$TRIM_FILESPEC

    The Fit Long File Specification into Fixed Field routine takes a
    file specification, such as an OpenVMS RMS resultant name string,
    and shortens it (if necessary) so that it fits into a field of
    fixed width.

    Format

      LIB$TRIM_FILESPEC  old-filespec ,new-filespec

                         [,word-integer-width] [,resultant-length]

2.223.1  –  Returns

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

2.223.2  –  Arguments

 old-filespec

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

    File specification to be trimmed. The old-filespec argument
    contains the address of a descriptor pointing to this file
    specification string.

    The file specification should be an RMS resultant name string.

 new-filespec

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

    Trimmed file specification. The new-filespec argument contains
    the address of a descriptor pointing to this trimmed file
    specification string. LIB$TRIM_FILESPEC writes the trimmed file
    specification into new-filespec.

 word-integer-width

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Maximum field width desired. The word-integer-width argument is
    the address of an unsigned word that contains this maximum field
    width.

    If omitted, the current length of new-filespec is used. If new-
    filespec is not a fixed-length string, you should specify word-
    integer-width to ensure that the desired width is used.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the trimmed file specification, not including any blank
    padding or truncated characters. The resultant-length argument is
    the address of an unsigned word that contains this length. This
    is an optional argument.

2.224  –  LIB$TRIM_FULLNAME

    The Trim a Full Name to Fit into a Desired Output Field routine
    trims a full name to fit into a desired output field. The
    trimming preserves the most significant part of the full name.

    Format

      LIB$TRIM_FULLNAME  fullname, trimmed-nodename [,output-width]

                         [,resultant-length]

2.224.1  –  Returns

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

2.224.2  –  Arguments

 fullname

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

    Full name to be trimmed. The fullname argument contains the
    address of a descriptor pointing to this full name string.

    The error LIB$_INVARG is returned if fullname contains an invalid
    full name, points to a null string, or contains more than 1024
    characters. The error LIB$_INVSTRDES is returned if fullname is
    an invalid descriptor.

 trimmed-nodename

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

    Trimmed node name. The trimmed-nodename argument contains the
    address of a descriptor pointing to the trimmed node-name string.
    LIB$TRIM_FULLNAME writes the trimmed node name into the buffer
    pointed to by trimmed-nodename.

    The error LIB$_INVSTRDES is returned if trimmed-nodename is an
    invalid descriptor.

    The length field of the trimmed-nodename descriptor is not
    updated unless trimmed-nodename is a dynamic descriptor with a
    length less than the resultant trimmed node name. Refer to the
    OpenVMS RTL String Manipulation (STR$) Manual for dynamic string
    descriptor usage.

    The trimmed-nodename argument contains an unusable result when
    LIB$TRIM_FULLNAME returns in error.

 output-width

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Field width desired for the trimmed node name. The output-width
    argument is the address of an unsigned word that contains this
    field width in bytes.

    If output-width is omitted, the current length of trimmed-
    nodename is used. If trimmed-nodename is not a fixed-length
    string, specify output-width to ensure that the desired width
    is used.

    If the lengths of both trimmed-nodename and output-width are
    specified, the length in output-width is used. In this case, if
    the current length of trimmed-nodename is smaller than the length
    of output-width, the output trimmed node name is truncated at the
    end, and the alternate successful status LIB$_STRTRU is returned.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the trimmed node name. The resultant-length argument
    is the address of an unsigned word that contains this length in
    bytes.

    The resultant-length argument contains an unusable result when
    LIB$TRIM_FULLNAME returns in error.

2.225  –  LIB$UNLOCK IMAGE (Alpha and I64 Only)

    Unlocks the specified image in the process's working set.

    Format

      LIB$UNLOCK_IMAGE  address

2.225.1  –  Returns

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

2.225.2  –  Arguments

 address

    OpenVMS usage:address
    type:         quadword
    access:       read only
    mechanism:    by value

    Address of a byte within the image to be unlocked in the working
    set. If the address argument is 0, the current image (which
    contains the call to LIB$UNLOCK_IMAGE) is unlocked in the working
    set.

2.226  –  LIB$VERIFY_VM_ZONE

    The Verify a Zone routine performs verification of a 32-bit zone.

    Format

      LIB$VERIFY_VM_ZONE  zone-id

2.226.1  –  Returns

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

2.226.2  –  Argument

 zone-id

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

    Zone identifier of the zone to be verified. The zone-id argument
    is the address of an unsigned longword that contains this zone
    identifier. A value of 0 indicates the 32-bit default zone.

2.227  –  LIB$VERIFY_VM_ZONE_64

    (Alpha and I64 only.) The Verify a Zone routine performs
    verification of a 64-bit zone.

    Format

      LIB$VERIFY_VM_ZONE_64  zone-id

2.227.1  –  Returns

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

2.227.2  –  Argument

 zone-id

    OpenVMS usage:identifier
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Zone identifier of the zone to be verified. The zone-id argument
    is the address of an unsigned quadword that contains this zone
    identifier. A value of 0 indicates the 64-bit default zone.

2.228  –  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]

2.228.1  –  Returns

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

2.228.2  –  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.

3  –  OTS$

3.1  –  OTS$CALL_PROC

    (Alpha and I64 only.) The Call Special Procedure routine performs
    a call to a procedure that may be either in native code or in a
    translated image.

    Format

      OTS$CALL_PROC  target-func-value ,target-sig-info

                     ,standard-args ,...

3.1.1  –  Returns

    None.

3.1.2  –  Arguments

 target-func-value

    OpenVMS usage:function value
    type:         quadword address
    access:       read only
    mechanism:     by value in register R23 (Alpha). by value in
                  register R17 (I64).
    Function value for the procedure to be called.

 target-sig-info

    OpenVMS usage:TIE signature information
    type:          TIE signature block
    access:       read only
    mechanism:     by reference in register R24 (Alpha). by value in
                  register R17 (I64).
    Signature information is used to transform the standard arguments
    into the form required by a translated image (if needed). The
    representation of signature information is described in the
    OpenVMS Calling Standard.

 standard-args

    type:
    access:
    mechanism:    0
    Zero or more arguments to be passed to the called routine, passed
    using standard conventions (including the AI register).

3.1.3  –  Description

    When translated code support is requested, the compiled code
    must call the special service routine, OTS$CALL_PROC. The actual
    parameters to the target function are passed to OTS$CALL_PROC as
    though the target routine is native code that is being invoked
    directly.

    OTS$CALL_PROC first determines whether the target routine is part
    of a translated image.

    If the target is in native code, then OTS$CALL_PROC completes
    the call in a way that makes its mediation transparent (that is,
    control need not pass back through it for the return). The native
    parameters are used without modification.

    If the target is in translated code, then OTS$CALL_PROC passes
    control to the Translated Image Environment (TIE).

3.1.4  –  Condition Values Returned

    None.

3.2  –  OTS$CNVOUT

    The Convert Floating to Character String routines convert a
    D-floating, G-floating, H-floating, IEEE S-floating, or IEEE
    T-floating number to a character string in the Fortran E format.

    Format

      OTS$CNVOUT  D-G-H-S-or-T-float-pt-input-val

                  ,fixed-length-resultant-string ,digits-in-fraction

      OTS$CNVOUT_G  D-G-H-S-or-T-float-pt-input-val

                    ,fixed-length-resultant-string

                    ,digits-in-fraction

      OTS$CNVOUT_H  D-G-H-S-or-T-float-pt-input-val

                    ,fixed-length-resultant-string

                    ,digits-in-fraction (VAX only)

      OTS$CNVOUT_S  D-G-H-S-or-T-float-pt-input-val

                    ,fixed-length-resultant-string

                    ,digits-in-fraction (VAX only)

      OTS$CNVOUT_T  D-G-H-S-or-T-float-pt-input-val

                    ,fixed-length-resultant-string

                    ,digits-in-fraction (VAX only)

3.2.1  –  Returns

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

3.2.2  –  Arguments

 D-G-H-S-or-T-float-pt-input-val

    OpenVMS usage:floating_point
    type:         D_floating, G_floating, H_floating, IEEE
                  S_floating, IEEE T_floating
    access:       read only
    mechanism:    by reference

    Value that OTS$CNVOUT converts to a character string. For
    OTS$CNVOUT, the D-G-H-S-or-T-float-pt-input-val argument is
    the address of a D-floating number containing the value. For
    OTS$CNVOUT_G, the D-G-H-S-or-T-float-pt-input-val argument is
    the address of a G-floating number containing the value. For
    OTS$CNVOUT_S, the D-G-H-S-or-T-float-pt-input-val argument is the
    address of an IEEE S-floating number containing the value. For
    OTS$CNVOUT_T, the D-G-H-S-or-T-float-pt-input-val argument is the
    address of an IEEE T-floating number containing the value.

 fixed-length-resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor, fixed length

    Output string into which OTS$CNVOUT writes the character string
    result of the conversion. The fixed-length-resultant-string
    argument is the address of a descriptor pointing to the output
    string.

 digits-in-fraction

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

    Number of digits in the fractional portion of the result. The
    digits-in-fraction argument is an unsigned longword containing
    the number of digits to be written to the fractional portion of
    the result.

3.3  –  OTS$CVT_L_TB

    The Convert an Unsigned Integer to Binary Text routine converts
    an unsigned integer value of arbitrary length to binary
    representation in an ASCII text string. By default, a longword
    is converted.

    Format

      OTS$CVT_L_TB  varying-input-value,fixed-length-resultant-string

                    [,number-of-digits] [,input-value-size]

3.3.1  –  Returns

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

3.3.2  –  Arguments

 varying-input-value

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

    Unsigned byte, word, or longword that OTS$CVT_L_TB converts to
    an unsigned decimal representation in an ASCII text string.
    (The value of the input-value-size argument determines whether
    varying-input-value is a byte, word, or longword.) The varying-
    input-value argument is the address of the unsigned integer.

 fixed-length-resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor, fixed length

    ASCII text string that OTS$CVT_L_TB creates when it converts the
    integer value. The fixed-length-resultant-string argument is the
    address of a descriptor pointing to this ASCII text string. The
    string is assumed to be of fixed length (CLASS_S descriptor).

 number-of-digits

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

    Minimum number of digits in the binary representation to be
    generated. The number-of-digits argument is a signed longword
    containing this minimum number. If the minimum number of digits
    is omitted, the default is 1. If the actual number of significant
    digits is less than the minimum number of digits, leading zeros
    are produced. If the minimum number of digits is zero and the
    value of the integer to be converted is also zero, OTS$CVT_L_TB
    creates a blank string.

 input-value-size

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

    Size of the integer to be converted, in bytes. The input-value-
    size argument is a signed longword containing the byte size. This
    is an optional argument. If the size is omitted, the default is 4
    (longword).

3.4  –  OTS$CVT_L_TI

    The Convert Signed Integer to Decimal Text routine converts a
    signed integer to its decimal representation in an ASCII text
    string. This routine supports Fortran Iw and Iw.m output and
    BASIC output conversion.

    Format

      OTS$CVT_L_TI  varying-input-value

                    ,fixed-length-resultant-string

                    [,number-of-digits] [,input-value-size]

                    [,flags-value]

3.4.1  –  Returns

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

3.4.2  –  Arguments

 varying-input-value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       read only
    mechanism:    by reference, fixed length

    A signed integer that OTS$CVT_L_TI converts to a signed decimal
    representation in an ASCII text string. The varying-input-value
    argument is the address of the signed integer.

    On VAX systems, the integer can be a signed byte, word, or
    longword. The value of the input-value-size argument determines
    whether varying-input-value is a byte, word, or longword.

    On Alpha and I64 systems, the integer can be a signed byte, word,
    longword, or quadword. The value of the input-value-size argument
    determines whether varying-input-value is a byte, word, longword,
    or quadword.

 fixed-length-resultant-string

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

    Decimal ASCII text string that OTS$CVT_L_TI creates when it
    converts the signed integer. The fixed-length-resultant-string
    argument is the address of a CLASS_S descriptor pointing to this
    text string. The string is assumed to be of fixed length.

 number-of-digits

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

    Minimum number of digits to be generated when OTS$CVT_L_TI
    converts the signed integer to a decimal ASCII text string.
    The number-of-digits argument is a signed longword containing
    this number. If the minimum number of digits is omitted, the
    default value is 1. If the actual number of significant digits
    is smaller, OTS$CVT_L_TI inserts leading zeros into the output
    string. If number-of-digits is zero and varying-input-value is
    zero, OTS$CVT_L_TI writes a blank string to the output string.

 input-value-size

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

    Size of the integer to be converted, in bytes. The input-value-
    size argument is a signed longword containing this value size. If
    the size is omitted, the default is 4 (longword).

    On VAX systems, the value size must be 1, 2, or 4. If value
    size is 1 or 2, the value is sign-extended to a longword before
    conversion.

    On Alpha and I64 systems, the value size must be 1, 2, 4, or
    8. If the value is 1, 2, or 4, the value is sign-extended to a
    quadword before conversion.

 flags-value

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

    Caller-supplied flags that you can use if you want OTS$CVT_L_TI
    to insert a plus sign before the converted number. The flags-
    value argument is an unsigned longword containing the flags.

    The caller flags are described in the following table:

    Bit  Action if Set         Action if Clear

    0    Insert a plus sign    Omit the plus sign.
         (+)  before the
         first nonblank
         character in the
         output string.

    If flags-value is omitted, all bits are clear and the plus sign
    is not inserted.

3.5  –  OTS$CVT_L_TL

    The Convert Integer to Logical Text routine converts an integer
    to an ASCII text string representation using Fortran L (logical)
    format.

    Format

      OTS$CVT_L_TL  longword-integer-value

                    ,fixed-length-resultant-string

3.5.1  –  Returns

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

3.5.2  –  Arguments

 longword-integer-value

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

    Value that OTS$CVT_L_TL converts to an ASCII text string. The
    longword-integer-value argument is the address of a signed
    longword containing this integer value.

 fixed-length-resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor, fixed length

    Output string that OTS$CVT_L_TL creates when it converts
    the integer value to an ASCII text string. The fixed-length-
    resultant-string argument is the address of a descriptor pointing
    to this ASCII text string.

    The output string is assumed to be of fixed length (CLASS_S
    descriptor).

    If bit 0 of longword-integer-value is set, OTS$CVT_L_TL stores
    the character T in the rightmost character of fixed-length-
    resultant-string. If bit 0 is clear, it stores the character
    F. In either case, it fills the remaining characters of fixed-
    length-resultant-string with blanks.

3.6  –  OTS$CVT_L_TO

    The Convert Unsigned Integer to Octal Text routine converts an
    unsigned integer to an octal ASCII text string. OTS$CVT_L_TO
    supports Fortran Ow and Ow.m output conversion formats.

    Format

      OTS$CVT_L_TO  varying-input-value

                    ,fixed-length-resultant-string

                    [,number-of-digits] [,input-value-size]

3.6.1  –  Returns

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

3.6.2  –  Arguments

 varying-input-value

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

    Unsigned byte, word, or longword that OTS$CVT_L_TO converts to
    an unsigned decimal representation in an ASCII text string.
    (The value of the input-value-size argument determines whether
    varying-input-value is a byte, word, or longword.) The varying-
    input-value argument is the address of the unsigned integer.

 fixed-length-resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor, fixed length

    Output string that OTS$CVT_L_TO creates when it converts the
    integer value to an octal ASCII text string. The fixed-length-
    resultant-string argument is the address of a descriptor pointing
    to the octal ASCII text string. The string is assumed to be of
    fixed length (CLASS_S descriptor).

 number-of-digits

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

    Minimum number of digits that OTS$CVT_L_TO generates when it
    converts the integer value to an octal ASCII text string. The
    number-of-digits argument is a signed longword containing the
    minimum number of digits. If it is omitted, the default is 1. If
    the actual number of significant digits in the octal ASCII text
    string is less than the minimum number of digits, OTS$CVT_L_TO
    inserts leading zeros into the output string. If number-of-digits
    is 0 and varying-input-value is 0, OTS$CVT_L_TO writes a blank
    string to the output string.

 input-value-size

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

    Size of the integer to be converted, in bytes. The input-value-
    size argument is a signed longword containing the number of bytes
    in the integer to be converted by OTS$CVT_L_TO. If it is omitted,
    the default is 4 (longword).

3.7  –  OTS$CVT_L_TU

    The Convert Unsigned Integer to Decimal Text routine converts an
    unsigned integer value to its unsigned decimal representation in
    an ASCII text string.

    Format

      OTS$CVT_L_TU  varying-input-value

                    ,fixed-length-resultant-string

                    [,number-of-digits] [,input-value-size]

3.7.1  –  Returns

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

3.7.2  –  Arguments

 varying-input-value

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

    An unsigned integer that OTS$CVT_L_TU converts to an unsigned
    decimal representation in an ASCII text string. The varying-
    input-value argument is the address of the unsigned integer.

    On VAX systems, the integer can be an unsigned byte, word, or
    longword. (The value of the input-value-size argument determines
    whether varying-input-value is a byte, word, or longword.)

    On Alpha and I64 systems, the integer can be an unsigned byte,
    word, longword, or quadword. (The value of the input-value-size
    argument determines whether varying-input-value is a byte, word,
    longword, or quadword.)

 fixed-length-resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor, fixed length

    Output string that OTS$CVT_L_TU creates when it converts the
    integer value to unsigned decimal representation in an ASCII text
    string. The fixed-length-resultant-string argument is the address
    of a descriptor pointing to this ASCII text string.

 number-of-digits

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

    Minimum number of digits in the ASCII text string that OTS$CVT_
    L_TU creates. The number-of-digits argument is a signed longword
    containing the minimum number. If the minimum number of digits is
    omitted, the default is 1.

    If the actual number of significant digits in the output string
    created is less than the minimum number, OTS$CVT_L_TU inserts
    leading zeros into the output string. If the minimum number of
    digits is zero and the integer value to be converted is also
    zero, OTS$CVT_L_TU writes a blank string to the output string.

 input-value-size

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

    Size of the integer to be converted, in bytes. The input-value-
    size argument is a signed longword containing this value size. If
    the size is omitted, the default is 4 (longword).

    On VAX systems, the value size must be 1, 2, or 4.

    On Alpha and I64 systems, the value size must be 1, 2, 4, or 8.

3.8  –  OTS$CVT_L_TZ

    The Convert Integer to Hexadecimal Text routine converts an
    unsigned integer to a hexadecimal ASCII text string. OTS$CVT_
    L_TZ supports Fortran Zw and Zw.m output conversion formats.

    Format

      OTS$CVT_L_TZ  varying-input-value

                    ,fixed-length-resultant-string

                    [,number-of-digits] [,input-value-size]

3.8.1  –  Returns

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

3.8.2  –  Arguments

 varying-input-value

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

    Unsigned byte, word, or longword that OTS$CVT_L_TZ converts to
    an unsigned decimal representation in an ASCII text string.
    (The value of the input-value-size argument determines whether
    varying-input-value is a byte, word, or longword.) The varying-
    input-value argument is the address of the unsigned integer.

 fixed-length-resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor, fixed length

    Output string that OTS$CVT_L_TZ creates when it converts the
    integer value to a hexadecimal ASCII text string. The fixed-
    length-resultant-string argument is the address of a descriptor
    pointing to this ASCII text string. The string is assumed to be
    of fixed length (CLASS_S descriptor).

 number-of-digits

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

    Minimum number of digits in the ASCII text string that OTS$CVT_
    L_TZ creates when it converts the integer. The number-of-digits
    argument is a signed longword containing this minimum number.
    If it is omitted, the default is 1. If the actual number of
    significant digits in the text string that OTS$CVT_L_TZ creates
    is less than this minimum number, OTS$CVT_L_TZ inserts leading
    zeros in the output string. If the minimum number of digits is
    zero and the integer value to be converted is also zero, OTS$CVT_
    L_TZ writes a blank string to the output string.

 input-value-size

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

    Size of the integer that OTS$CVT_L_TZ converts, in bytes. The
    input-value-size argument is a signed longword containing the
    value size. If the size is omitted, the default is 4 (longword).

3.9  –  OTS$CVT T x

    The Convert Numeric Text to D-, F-, G-, H-, IEEE S-, or IEEE T-
    Floating routines convert an ASCII text string representation
    of a numeric value to a D-floating, F-floating, G-floating, H-
    floating, IEEE S-floating, or IEEE T-floating value.

    Format

      OTS$CVT_T_D  fixed-or-dynamic-input-string

                   ,floating-point-value [,digits-in-fraction]

                   [,scale-factor] [,flags-value] [,extension-bits]

      OTS$CVT_T_F  fixed-or-dynamic-input-string

                   ,floating-point-value [,digits-in-fraction]

                   [,scale-factor] [,flags-value] [,extension-bits]

      OTS$CVT_T_G  fixed-or-dynamic-input-string

                   ,floating-point-value [,digits-in-fraction]

                   [,scale-factor] [,flags-value] [,extension-bits]

      OTS$CVT_T_H  fixed-or-dynamic-input-string

                   ,floating-point-value [,digits-in-fraction]

                   [,scale-factor] [,flags-value] [,extension-bits]

      OTS$CVT_T_S  fixed-or-dynamic-input-string

                   ,floating-point-value [,digits-in-fraction]

                   [,scale-factor] [,flags-value] [,extension-bits]

      OTS$CVT_T_T  fixed-or-dynamic-input-string

                   ,floating-point-value [,digits-in-fraction]

                   [,scale-factor] [,flags-value] [,extension-bits]

3.9.1  –  Returns

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

3.9.2  –  Arguments

 fixed-or-dynamic-input-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor, fixed-length or dynamic string

    Input string containing an ASCII text string representation of
    a numeric value that OTS$CVT_T_x converts to a D-floating, F-
    floating, G-floating, H-floating, IEEE S-floating, or IEEE T-
    floating value. The fixed-or-dynamic-input-string argument is the
    address of a descriptor pointing to the input string.

    The syntax of a valid input string is as follows:

    [blanks][+ or -][digits][.][digits][+ or -][digits]

       or

    [blanks][+ or -][digits][.][digits][ X ][digits]

       where X = {E e D d Q q}[blanks][+ or -]

    E, e, D, d, Q, and q are the possible exponent letters. They are
    semantically equivalent. Other elements in the preceding syntax
    are defined as follows:

    Term           Description

    blanks         One or more blanks
    digits         One or more decimal digits

 floating-point-value

    OpenVMS usage:floating_point
    type:         D_floating, F_floating, G_floating, H_floating,
                  IEEE S_floating, IEEE T_floating
    access:       write only
    mechanism:    by reference

    Floating-point value that OTS$CVT_T_x creates when it converts
    the input string. The floating-point-value argument is the
    address of the floating-point value. The data type of floating-
    point-value depends on the called routine as shown in the
    following table:

    Routine          floating-point-value Data Type

    OTS$CVT_T_D      D-floating
    OTS$CVT_T_F      F-floating
    OTS$CVT_T_G      G-floating
    OTS$CVT_T_H      H-floating
    OTS$CVT_T_S      IEEE S-floating
    OTS$CVT_T_T      IEEE T-floating

 digits-in-fraction

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

    Number of digits in the fraction if no decimal point is included
    in the input string. The digits-in-fraction argument contains the
    number of digits. If the number of digits is omitted, the default
    is zero.

 scale-factor

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

    Scale factor. The scale-factor argument contains the value of
    the scale factor. If bit 6 of the flags-value argument is clear,
    the resultant value is divided by 10**scale-factor unless the
    exponent is present. If bit 6 of flags-value is set, the scale
    factor is always applied. If the scale factor is omitted, the
    default is zero.

 flags-value

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

    User-supplied flags. The flags-value argument contains the user-
    supplied flags described in the following table:

    Bit  Action if Set         Action if Clear

    0    Ignore blanks.        Interpret blanks as zeros.
    1    Allow only E or e     Allow E, e, D, d, Q and q exponents.
         exponents. (This      (This is consistent with BASIC
         is consistent with    semantics.)
         Fortran semantics.)
    2    Interpret an          Do not interpret an underflow as an
         underflow as an       error.
         error.
    3    Truncate the value.   Round the value.
    4    Ignore tabs.          Interpret tabs as invalid characters.
    5    An exponent must      The exponent letter can be omitted.
         begin with a valid
         exponent letter.
    6    Always apply the      Apply the scale factor only if there
         scale factor.         is no exponent present in the string.

    If you omit the flags-value argument, OTS$CVT_T_x defaults all
    flags to clear.

 extension-bits (D-, F-floating, IEEE S-floating)

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       write only
    mechanism:    by reference

 extension-bits (G-, H-floating, IEEE T-floating)

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Extra precision bits. The extension-bits argument is the address
    of a word containing the extra precision bits. If extension-
    bits is present, floating-point-value is not rounded, and the
    first n bits after truncation are returned left-justified in this
    argument, as follows:

                     Number
                     of Bits
    Routine          Returned  Data Type

    OTS$CVT_T_D      8         Byte (unsigned)
    OTS$CVT_T_F      8         Byte (unsigned)
    OTS$CVT_T_G      11        Word (unsigned)
    OTS$CVT_T_H      15        Word (unsigned)
    OTS$CVT_T_S      8         Byte (unsigned)
    OTS$CVT_T_T      11        Word (unsigned)

    A value represented by extension bits is suitable for use as the
    extension operand in an EMOD instruction.

    The extra precision bits returned for H-floating may not be
    precise because OTS$CVT_T_H carries its calculations to only
    128 bits. However the error should be small.

3.10  –  OTS$CVT_TB_L

    The Convert Binary Text to Unsigned Integer routine converts an
    ASCII text string representation of an unsigned binary value to
    an unsigned integer value. The integer value can be of arbitrary
    length but is typically a byte, word, longword, or quadword. The
    default size of the result is a longword.

    Format

      OTS$CVT_TB_L  fixed-or-dynamic-input-string

                    ,varying-output-value [,output-value-size]

                    [,flags-value]

3.10.1  –  Returns

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

3.10.2  –  Arguments

 fixed-or-dynamic-input-string

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

    Input string containing the string representation of an unsigned
    binary value that OTS$CVT_TB_L converts to an unsigned integer
    value. The fixed-or-dynamic-input-string argument is the
    address of a descriptor pointing to the input string. The valid
    input characters are blanks and the digits 0 and 1. No sign is
    permitted.

 varying-output-value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    Unsigned integer of specified size that OTS$CVT_TB_L creates
    when it converts the ASCII text string. The varying-output-value
    argument is the address of the integer. The value of the output-
    value-size argument determines the size in bytes of the output
    value.

 output-value-size

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

    Arbitrary number of bytes to be occupied by the unsigned integer
    output value. The output-value-size argument contains a value
    that equals the size in bytes of the output value. If the value
    of output-value-size is zero or a negative number, OTS$CVT_TB_L
    returns an input conversion error. If you omit the output-value-
    size argument, the default is 4 (longword).

 flags-value

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

    User-supplied flag that OTS$CVT_TB_L uses to determine how
    to interpret blanks within the input string. The flags-value
    argument contains this user-supplied flag.

    OTS$CVT_TB_L defines the flag as follows:

    Bit  Action if Set    Action if Clear

    0    Ignore blanks.   Interpret blanks as zeros.

    If you omit the flags-value argument, OTS$CVT_TB_L defaults all
    flags to clear.

3.11  –  OTS$CVT_TI_L

    The Convert Signed Integer Text to Integer routine converts an
    ASCII text string representation of a signed decimal number
    to a signed integer value. The default size of the result is a
    longword.

    Format

      OTS$CVT_TI_L  fixed-or-dynamic-input-string

                    ,varying-output-value [,output-value-size]

                    [,flags-value]

3.11.1  –  Returns

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

3.11.2  –  Arguments

 fixed-or-dynamic-input-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor, fixed-length or dynamic string

    Input ASCII text string that OTS$CVT_TI_L converts to a signed
    integer. The fixed-or-dynamic-input-string argument is the
    address of a descriptor pointing to the input string.

    [+ or -]<integer-digits>

    OTS$CVT_TI_L always ignores leading blanks.

 varying-output-value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    Signed integer that OTS$CVT_TI_L creates when it converts the
    ASCII text string. The varying-output-value argument is the
    address of the signed integer. The value of the output-value-size
    argument determines the size of varying-output-value.

 output-value-size

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

    Number of bytes to be occupied by the value created when OTS$CVT_
    TI_L converts the ASCII text string to an integer value. The
    output-value-size argument contains the number of bytes in
    varying-output-value.

    On VAX systems, valid values for the output-value-size argument
    are 1, 2, and 4. The value determines whether the integer value
    that OTS$CVT_TI_L creates is a byte, word, or longword.

    On Alpha and I64 systems, valid values for the output-value-
    size argument are 1, 2, 4, and 8. The value determines whether
    the integer value that OTS$CVT_TI_L creates is a byte, word,
    longword, or quadword.

    For VAX and Alpha systems, if you specify a 0 (zero) or omit the
    output-value-size argument, the size of the output value defaults
    to 4 (longword). If you specify any other value, OTS$CVT_TI_L
    returns an input conversion error.

 flags-value

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

    User-supplied flags that OTS$CVT_TI_L uses to determine how
    blanks and tabs are interpreted. The flags-value argument is
    an unsigned longword containing the value of the flags.

    Bit  Action if Set    Action if Clear

    0    Ignore all       Ignore leading blanks but interpret blanks
         blanks.          after the first legal character as zeros.
    4    Ignore tabs.     Interpret tabs as invalid characters.

    If you omit the flags-value argument, OTS$CVT_TI_L defaults all
    flags to clear.

3.12  –  OTS$CVT_TL_L

    The Convert Logical Text to Integer routine converts an ASCII
    text string representation of a FORTRAN-77 L format to a signed
    integer.

    Format

      OTS$CVT_TL_L  fixed-or-dynamic-input-string

                    ,varying-output-value [,output-value-size]

3.12.1  –  Returns

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

3.12.2  –  Arguments

 fixed-or-dynamic-input-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor, fixed-length or dynamic string

    Input string containing an ASCII text representation of a
    FORTRAN-77 L format that OTS$CVT_TL_L converts to a signed
    integer value. The fixed-or-dynamic-input-string argument is
    the address of a descriptor pointing to the input string.

    Common ASCII text representations of a FORTRAN-77 logical are
    .TRUE., .FALSE., T, t, F, and f. In practice, an OTS$CVT_TL_L
    input string is valid if it adheres to the following syntax:

    <blanks>

        or

    [<blanks>][.]{T t F f}[<characters>]

    One of the letters T, t, F, or f is required. Other elements in
    the preceding syntax are defined as follows:

    Term         Description

    blanks       One or more blanks
    characters   One or more of any character

 varying-output-value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    Signed integer that OTS$CVT_TL_L creates when it converts the
    ASCII text string. The varying-output-value argument is the
    address of the signed integer. The value of the output-value-size
    argument determines the size in bytes of the signed integer.

    OTS$CVT_TL_L returns -1 as the contents of the varying-output-
    value argument if the character denoted by "letter" is T or t.
    Otherwise, OTS$CVT_TL_L sets varying-output-value to zero.

 output-value-size

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

    Number of bytes to be occupied by the signed integer created
    when OTS$CVT_TL_L converts the ASCII text string to an integer
    value. The output-value-size argument contains a value that
    equals the size in bytes of the output value. If output-value-
    size contains a zero or a negative number, OTS$CVT_TL_L returns
    an input conversion error.

    On VAX systems, valid values for the output-value-size argument
    are 1, 2, and 4. The value determines whether the integer value
    that OTS$CVT_TL_L creates is a byte, word, or longword.

    On Alpha and I64 systems, valid values for the output-value-
    size argument are 1, 2, 4, and 8. This value determines whether
    the integer value that OTS$CVT_TL_L creates is a byte, word,
    longword, or quadword.

    For VAX, Alpha, and I64 systems, if you omit the output-value-
    size argument, the default is 4 (longword).

3.13  –  OTS$CVT_TO_L

    The Convert Octal Text to Unsigned Integer routine converts an
    ASCII text string representation of an unsigned octal value to
    an unsigned integer. The integer value can be of arbitrary length
    but is typically a byte, word, longword, or quadword. The default
    size of the result is a longword.

    Format

      OTS$CVT_TO_L  fixed-or-dynamic-input-string

                    ,varying-output-value [,output-value-size]

                    [,flags-value]

3.13.1  –  Returns

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

3.13.2  –  Arguments

 fixed-or-dynamic-input-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor, fixed-length or dynamic string

    Input string containing the string representation of an unsigned
    octal value that OTS$CVT_TO_L converts to an unsigned integer.
    The fixed-or-dynamic-input-string argument is the address of
    a descriptor pointing to the input string. The valid input
    characters are blanks and the digits 0 through 7. No sign is
    permitted.

 varying-output-value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    Unsigned integer of specified size that OTS$CVT_TO_L creates
    when it converts the ASCII text string. The varying-output-value
    argument is the address of the unsigned integer. The value of the
    output-value-size argument determines the size in bytes of the
    output value.

 output-value-size

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

    Arbitrary number of bytes to be occupied by the unsigned integer
    output value. The output-value-size argument contains a value
    that equals the size in bytes of the output value. If the value
    of output-value-size is zero or a negative number, OTS$CVT_TO_L
    returns an input conversion error. If you omit the output-value-
    size argument, the default is 4 (longword).

 flags-value

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

    User-supplied flag that OTS$CVT_TO_L uses to determine how
    to interpret blanks within the input string. The flags-value
    argument contains the user-supplied flag described in the
    following table:

    Bit  Action if Set    Action if Clear

    0    Ignore all       Interpret blanks as zeros.
         blanks.

    If you omit the flags-value argument, OTS$CVT_TO_L defaults the
    flag to clear.

3.14  –  OTS$CVT_TU_L

    The Convert Unsigned Decimal Text to Integer routine converts an
    ASCII text string representation of an unsigned decimal value to
    an unsigned integer value. By default, the size of the result is
    a longword.

    Format

      OTS$CVT_TU_L  fixed-or-dynamic-input-string

                    ,varying-output-value [,output-value-size]

                    [,flags-value]

3.14.1  –  Returns

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

3.14.2  –  Arguments

 fixed-or-dynamic-input-string

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

    Input string containing an ASCII text string representation of an
    unsigned decimal value that OTS$CVT_TU_L converts to an unsigned
    integer value. The fixed-or-dynamic-input-string argument is the
    address of a descriptor pointing to the input string. Valid input
    characters are the space and the digits 0 through 9. No sign is
    permitted.

 varying-output-value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    Unsigned integer that OTS$CVT_TU_L creates when it converts
    the ASCII text string. The varying-output-value argument is the
    address of the unsigned integer. The value of the output-value-
    size argument determines the size of varying-output-value.

 output-value-size

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

    Number of bytes occupied by the value created when OTS$CVT_
    TU_L converts the input string. The output-value-size argument
    contains the number of bytes in varying-output-value.

    On VAX systems, valid values for the output-value-size argument
    are 1, 2, and 4. The value determines whether the integer value
    that OTS$CVT_TU_L creates is a byte, word, or longword.

    On Alpha and I64 systems, valid values for the output-value-
    size argument are 1, 2, 4, and 8. The value determines whether
    the integer value that OTS$CVT_TU_L creates is a byte, word,
    longword, or quadword.

    For VAX, Alpha, and I64 systems, if you specify a 0 (zero) or
    omit the output-value-size argument, the size of the output
    value defaults to 4 (longword). If you specify any other value,
    OTS$CVT_TU_L returns an input conversion error.

 flags-value

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

    User-supplied flags that OTS$CVT_TU_L uses to determine how
    blanks and tabs are interpreted. The flags-value argument
    contains the user-supplied flags as described in the following
    table:

    Bit  Action if Set    Action if Clear

    0    Ignore all       Ignore leading blanks but interpret blanks
         blanks.          after the first legal character as zeros.
    4    Ignore tabs.     Interpret tabs as invalid characters.

    If you omit the flags-value argument, OTS$CVT_TU_L defaults all
    flags to clear.

3.15  –  OTS$CVT_TZ_L

    The Convert Hexadecimal Text to Unsigned Integer routine converts
    an ASCII text string representation of an unsigned hexadecimal
    value to an unsigned integer. The integer value can be of
    arbitrary length but is typically a byte, word, longword, or
    quadword. The default size of the result is a longword.

    Format

      OTS$CVT_TZ_L  fixed-or-dynamic-input-string

                    ,varying-output-value [,output-value-size]

                    [,flags-value]

3.15.1  –  Returns

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

3.15.2  –  Arguments

 fixed-or-dynamic-input-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor, fixed-length or dynamic string

    Input string containing the string representation of an unsigned
    hexadecimal value that OTS$CVT_TZ_L converts to an unsigned
    integer. The fixed-or-dynamic-input-string argument is the
    address of a descriptor pointing to the input string. The valid
    input characters are blanks, the digits 0 through 7, and the
    letters A through F. Letters can be uppercase or lowercase. No
    sign is permitted.

 varying-output-value

    OpenVMS usage:varying_arg
    type:         unspecified
    access:       write only
    mechanism:    by reference

    Unsigned integer of specified size that OTS$CVT_TZ_L creates
    when it converts the ASCII text string. The varying-output-value
    argument is the address of the unsigned integer. The value of the
    output-value-size argument determines the size in bytes of the
    output value.

 output-value-size

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

    Arbitrary number of bytes to be occupied by the unsigned integer
    output value. The output-value-size argument contains a value
    that equals the size in bytes of the output value. If the value
    of output-value-size is zero or a negative number, OTS$CVT_TZ_L
    returns an input conversion error. If you omit the output-value-
    size argument, the default is 4 (longword).

 flags-value

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

    User-supplied flags that OTS$CVT_TZ_L uses to determine how
    to interpret blanks within the input string. The flags-value
    argument contains these user-supplied flags as described in the
    following table:

    Bit  Action if Set    Action if Clear

    0    Ignore all       Interpret blanks as zeros.
         blanks.

    If you omit the flags-value argument, OTS$CVT_TZ_L defaults the
    flag to clear.

3.16  –  OTS$DIVCx

    The Complex Division routines return a complex result of a
    division on complex numbers.

    Format

      OTS$DIVC  complex-dividend ,complex-divisor

      OTS$DIVCD_R3  complex-dividend ,complex-divisor (VAX only)

      OTS$DIVCG_R3  complex-dividend ,complex-divisor

      OTS$DIVCS  complex-dividend ,complex-divisor

      OTS$DIVCT_R3  complex-dividend ,complex-divisor

3.16.1  –  Returns

    OpenVMS usage:complex_number
    type:         F_floating complex, D_floating complex, G_floating
                  complex, IEEE S_floating complex, IEEE T_floating
                  complex,
    access:       write only
    mechanism:    by value

    Complex result of complex division. OTS$DIVC returns an F-
    floating complex number. OTS$DIVCD_R3 returns a D-floating
    complex number. OTS$DIVCG_R3 returns a G-floating complex number.
    OST$DIVCS returns an IEEE S-floating complex number. OTS$DIVCT_R3
    returns an IEEE T-floating complex number.

3.16.2  –  Arguments

 complex-dividend

    OpenVMS usage:complex_number
    type:         F_floating complex, D_floating complex, G_floating
                  complex, IEEE S_floating complex, IEEE T_floating
                  complex
    access:       read only
    mechanism:    by value

    Complex dividend. The complex-dividend argument contains a
    floating-point complex value. For OTS$DIVC, complex-dividend
    is an F-floating complex number. For OTS$DIVCD_R3, complex-
    dividend is a D-floating complex number. For OTS$DIVCG_R3,
    complex-dividend is a G-floating complex number. For OTS$DIVCT_
    R3, complex-dividend is an IEEE T-floating complex number.

 complex-divisor

    OpenVMS usage:complex_number
    type:         F_floating complex, D_floating complex, G_floating
                  complex, IEEE S_floating complex, IEEE T_floating
                  complex
    access:       read only
    mechanism:    by value

    Complex divisor. The complex-divisor argument contains the value
    of the divisor. For OTS$DIVC, complex-divisor is an F-floating
    complex number. For OTS$DIVCD_R3, complex-divisor is a D-floating
    complex number. For OTS$DIVCG_R3, complex-divisor is a G-floating
    complex number. For OTS$DIVCS, complex-divisor is an IEEE S-
    floating complex number. For OTS$DIVCS, complex-dividend is an
    IEEE S-floating complex number. For OTS$DIVCT_R3, complex-divisor
    is an IEEE T-floating complex number.

3.17  –  OTS$DIV_PK_LONG

    The Packed Decimal Division with Long Divisor routine divides
    fixed-point decimal data, which is stored in packed decimal form,
    when precision and scale requirements for the quotient call for
    multiple precision division. The divisor must have a precision of
    30 or 31 digits.

    Format

      OTS$DIV_PK_LONG  packed-decimal-dividend

                       ,packed-decimal-divisor ,divisor-precision

                       ,packed-decimal-quotient ,quotient-precision

                       ,precision-data ,scale-data

3.17.1  –  Returns

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

3.17.2  –  Arguments

 packed-decimal-dividend

    OpenVMS usage:varying_arg
    type:         packed decimal string
    access:       read only
    mechanism:    by reference

    Dividend. The packed-decimal-dividend argument is the address of
    a packed decimal string that contains the shifted dividend.

    Before being passed as input, the packed-decimal-dividend
    argument is always multiplied by 10**c, where c is defined as
    follows:

    c = 31 - prec(packed-decimal-dividend)

    Multiplying packed-decimal-dividend by 10**c makes packed-
    decimal-dividend a 31-digit number.

 packed-decimal-divisor

    OpenVMS usage:varying_arg
    type:         packed decimal string
    access:       read only
    mechanism:    by reference

    Divisor. The packed-decimal-divisor argument is the address of a
    packed decimal string that contains the divisor.

 divisor-precision

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by value

    Precision of the divisor. The divisor-precision argument is a
    signed word that contains the precision of the divisor. The high-
    order bits are filled with zeros.

 packed-decimal-quotient

    OpenVMS usage:varying_arg
    type:         packed decimal string
    access:       write only
    mechanism:    by reference

    Quotient. The packed-decimal-quotient argument is the address of
    the packed decimal string into which OTS$DIV_PK_LONG writes the
    quotient.

 quotient-precision

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by value

    Precision of the quotient. The quotient-precision argument is
    a signed word that contains the precision of the quotient. The
    high-order bits are filled with zeros.

 precision-data

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by value

    Additional digits of precision required. The precision-data
    argument is a signed word that contains the value of the
    additional digits of precision required.

    OTS$DIV_PK_LONG computes the precision-data argument as follows:

    precision-data = scale(packed-decimal-quotient)
    + scale(packed-decimal-divisor)
    - scale(packed-decimal-dividend)
    - 31 + prec(packed-decimal-dividend)

 scale-data

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by value

    Scale factor of the decimal point. The scale-data argument is a
    signed word that contains the scale data.

    OTS$DIV_PK_LONG defines the scale-data argument as follows:

    scale-data = 31 - prec(packed-decimal-divisor)

3.18  –  OTS$DIV_PK_SHORT

    The Packed Decimal Division with Short Divisor routine divides
    fixed-point decimal data when precision and scale requirements
    for the quotient call for multiple-precision division.

    Format

      OTS$DIV_PK_SHORT  packed-decimal-dividend

                        ,packed-decimal-divisor ,divisor-precision

                        ,packed-decimal-quotient ,quotient-precision

                        ,precision-data

3.18.1  –  Returns

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

3.18.2  –  Arguments

 packed-decimal-dividend

    OpenVMS usage:varying_arg
    type:         packed decimal string
    access:       read only
    mechanism:    by reference

    Dividend. The packed-decimal-dividend argument is the address of
    a packed decimal string that contains the shifted dividend.

    Before being passed as input, the packed-decimal-dividend
    argument is always multiplied by 10**c, where c is defined as
    follows:

    c = 31 - prec(packed-decimal-dividend)

    Multiplying packed-decimal-dividend by 10**c makes packed-
    decimal-dividend a 31-digit number.

 packed-decimal-divisor

    OpenVMS usage:varying_arg
    type:         packed decimal string
    access:       read only
    mechanism:    by reference

    Divisor. The packed-decimal-divisor argument is the address of a
    packed decimal string that contains the divisor.

 divisor-precision

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by value

    Precision of the divisor. The divisor-precision argument is a
    signed word integer that contains the precision of the divisor;
    high-order bits are filled with zeros.

 packed-decimal-quotient

    OpenVMS usage:varying_arg
    type:         packed decimal string
    access:       write only
    mechanism:    by reference

    Quotient. The packed-decimal-quotient argument is the address of
    a packed decimal string into which OTS$DIV_PK_SHORT writes the
    quotient.

 quotient-precision

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by value

    Precision of the quotient. The quotient-precision argument is a
    signed word that contains the precision of the quotient; high-
    order bits are filled with zeros.

 precision-data

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by value

    Additional digits of precision required. The precision-data
    argument is a signed word that contains the value of the
    additional digits of precision required.

    OTS$DIV_PK_SHORT computes the precision-data argument as follows:

    precision-data = scale(packed-decimal-quotient)
    + scale(packed-decimal-divisor)
    - scale(packed-decimal-dividend)
    - 31 + prec(packed-decimal-dividend)

3.19  –  OTS$JUMP_TO_BPV

    I64 only.

    The Jump to Bound Procedure Value routine transfers control to a
    bound procedure.

    Format

      OTS$JUMP_TO_BPV  bound-func-value ,standard-args ,...

3.19.1  –  Returns

    None.

3.19.2  –  Arguments

 bound-func-value

    OpenVMS usage:quadword address
    type:         address
    access:       read only
    mechanism:    by value in register R1 (GP)
    Function value for the procedure being called.

 standard-args

    type:
    access:
    mechanism:    0
    Zero or more arguments to be passed to the called routine, passed
    using standard conventions (including the AI register).

3.19.3  –  Description

    When a procedure value that refers to a bound procedure
    descriptor is used to make a call, the routine designated in
    the OTS_ENTRY field (typically OTS$JUMP_TO_BPV) receives control
    with the GP register pointing to the bound procedure descriptor
    (instead of a global offset table). This routine performs the
    following steps:

    1. Load the "real" target entry address into a volatile branch
       register, for example, B6.

    2. Load the dynamic environment value into the appropriate
       uplevel-addressing register for the target function, for
       example, OTS$JUMP_TO_BPV uses R9.

    3. Load the "real" target GP address into the GP register

    4. Transfer control (branch, not call) to the target entry
       address.

    Control arrives at the real target procedure address with both
    the GP and environment register values established appropriately.

    Support routine OTS$JUMP_TO_BPV is included as a standard library
    routine. The operation of OTS$JUMP_TO_BPV is logically equivalent
    to the following code:

       OTS$JUMP_TO_BPV::
            add     gp=gp,24        ; Adjust GP to point to entry address
            ld8     r9=[gp],16      ; Load target entry address
            mov     b6=r9
            ld8     r9=[gp],-8      ; Load target environment value
            ld8     gp=[gp]         ; Load target GP
            br      b6              ; Transfer to target

    Note that there can be multiple OTS$JUMP_TO_BPV-like support
    routines, corresponding to different target registers where
    the environment value should be placed. The code that creates
    the bound function descriptor is also necessarily compiled by
    the same compiler that compiles the target procedure, thus can
    correctly select an appropriate support routine.

3.19.4  –  Condition Values Returned

    None.

3.20  –  OTS$MOVE3

    The Move Data Without Fill routine moves up to 2**31-1 bytes
    (2,147,483,647 bytes) from a specified source address to a
    specified destination address.

    Format

      OTS$MOVE3  length-value ,source-array ,destination-array

3.20.1  –  Corresponding JSB Entry Point

      OTS$MOVE3_R5

3.20.2  –  Returns

    None.

3.20.3  –  Arguments

 length-value

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by value
    Number of bytes of data to move. The length-value argument is a
    signed longword that contains the number of bytes to move. The
    value of length-value may range from 0 to 2,147,483,647 bytes.

 source-array

    OpenVMS usage:vector_byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference, array reference
    Data to be moved by OTS$MOVE3. The source-array argument contains
    the address of an unsigned byte array that contains this data.

 destination-array

    OpenVMS usage:vector_byte_unsigned
    type:         byte (unsigned)
    access:       write only
    mechanism:    by reference, array reference
    Address into which source-array will be moved. The destination-
    array argument is the address of an unsigned byte array into
    which OTS$MOVE3 writes the source data.

3.21  –  OTS$MOVE5

    The Move Data with Fill routine moves up to 2**32-1 bytes
    (2,147,483,647 bytes) from a specified source address to
    a specified destination address, with separate source and
    destination lengths, and with fill. Overlap of the source and
    destination arrays does not affect the result.

    Format

      OTS$MOVE5  longword-int-source-length ,source-array ,fill-value

                 ,longword-int-dest-length ,destination-array

3.21.1  –  Corresponding JSB Entry Point

      OTS$MOVE5_R5

3.21.2  –  Returns

    None.

3.21.3  –  Arguments

 longword-int-source-length

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

    Number of bytes of data to move. The longword-int-source-
    length argument is a signed longword that contains this number.
    The value of longword-int-source-length may range from 0 to
    2,147,483,647.

 source-array

    OpenVMS usage:vector_byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference, array reference

    Data to be moved by OTS$MOVE5. The source-array argument contains
    the address of an unsigned byte array that contains this data.

 fill-value

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by value

    Character used to pad the source data if longword-int-source-
    length is less than longword-int-dest-length. The fill-value
    argument contains the address of an unsigned byte that is this
    character.

 longword-int-dest-length

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

    Size of the destination area in bytes. The longword-int-dest-
    length argument is a signed longword containing this size.
    The value of longword-int-dest-length may range from 0 through
    2,147,483,647.

 destination-array

    OpenVMS usage:vector_byte_unsigned
    type:         byte (unsigned)
    access:       write only
    mechanism:    by reference, array reference

    Address into which source-array is moved. The destination-array
    argument is the address of an unsigned byte array into which
    OTS$MOVE5 writes the source data.

3.22  –  OTS$MULCx

    The Complex Multiplication routines calculate the complex product
    of two complex values.

    Format

      OTS$MULCD_R3  complex-multiplier ,complex-multiplicand (VAX

                    only)

      OTS$MULCG_R3  complex-multiplier ,complex-multiplicand

      OTS$MULCT_R3  complex-multiplier ,complex-multiplicand

      OTS$MULCS  complex-multiplier ,complex-multiplicand

3.22.1  –  Returns

    OpenVMS usage:complex_number
    type:         D_floating complex, G_floating complex, IEEE
                  S_floating complex, IEEE T_floating complex,
    access:       write only
    mechanism:    by value

    Complex result of multiplying two complex numbers. OTS$MULCD_
    R3 returns a D-floating complex number. OTS$MULCG_R3 returns a
    G-floating complex number. OTS$MULCS returns an IEEE S-Floating
    complex number. OTS$MULCT_R3 returns an IEEE T-floating complex
    number.

3.22.2  –  Arguments

 complex-multiplier

    OpenVMS usage:complex_number
    type:         D_floating complex, G_floating complex, S_floating
                  complex, S_floating complex
    access:       read only
    mechanism:    by value

    Complex multiplier. The complex-multiplier argument contains the
    complex multiplier. For OTS$MULCD_R3, complex-multiplier is a
    D-floating complex number. For OTS$MULCG_R3, complex-multiplier
    is a G-floating complex number. For OTS$MULCS, complex-multiplier
    is a IEEE S-Floating complex number. For OTS$MULCT_R3, complex-
    multiplier is an IEEE T-floating complex number.

 complex-multiplicand

    OpenVMS usage:complex_number
    type:         D_floating complex, G_floating complex, IEEE
                  S_floating complex, IEEE T_floating complex
    access:       read only
    mechanism:    by value

    Complex multiplicand. The complex-multiplicand argument contains
    the complex multiplicand. For OTS$MULCD_R3, complex-multiplicand
    is a D-floating complex number. For OTS$MULCG_R3, complex-
    multiplicand is a G-floating complex number. For OTS$MULCS,
    complex-multiplicand is an IEEE S-floating complex number. For
    OTS$MULCT_R3, complex-multiplicand is an IEEE T-floating complex
    number.

3.23  –  OTS$POWCxCx

    The Raise a Complex Base to a Complex Floating-Point Exponent
    routines raise a complex base to a complex exponent.

    Format

      OTS$POWCC  complex-base ,complex-exponent-value

      OTS$POWCDCD_R3  complex-base ,complex-exponent-value (VAX only)

      OTS$POWCGCG_R3  complex-base ,complex-exponent-value

      OTS$POWCSCS  complex-base ,complex-exponent-value

      OTS$POWCTCT_R3  complex-base ,complex-exponent-value

3.23.1  –  Returns

    OpenVMS usage:complex_number
    type:         F_floating complex, D_floating complex, G_floating
                  complex, IEEE S_floating complex, IEEE T_floating
                  complex
    access:       write only
    mechanism:    by value

    Result of raising a complex base to a complex exponent. OTS$POWCC
    returns an F-floating complex number. OTS$POWCDCD_R3 returns a
    D-floating complex number. OTS$POWCGCG_R3 returns a G-floating
    complex number. OTS$POWCSCS returns an IEEE S-floating complex
    number. OTS$POWCTCT_R3 returns an IEEE T-floating complex number.

3.23.2  –  Arguments

 complex-base

    OpenVMS usage:complex_number
    type:         F_floating complex, D_floating complex, G_floating
                  complex, IEEE S_floating complex, IEEE T_floating
                  complex
    access:       read only
    mechanism:    by value

    Complex base. The complex-base argument contains the value of
    the base. For OTS$POWCC, complex-base is an F-floating complex
    number. For OTS$POWCDCD_R3, complex-base is a D-floating complex
    number. For OTS$POWCGCG_R3, complex-base is a G-floating complex
    number. For OTS$POWCSCS, complex-base is an IEEE S-floating
    complex number. For OTS$POWCTCT_R3, complex-base is an IEEE T-
    floating complex number.

 complex-exponent-value

    OpenVMS usage:complex_number
    type:         F_floating complex, D_floating complex, G_floating
                  complex, IEEE S_floating complex, IEEE T_floating
                  complex
    access:       read only
    mechanism:    by value

    Complex exponent. The complex-exponent-value argument contains
    the value of the exponent. For OTS$POWCC, complex-exponent-value
    is an F-floating complex number. For OTS$POWCDCD_R3, complex-
    exponent-value is a D-floating complex number. For OTS$POWCGCG_
    R3, complex-exponent-value is a G-floating complex number. For
    OTS$POWCSCS, complex-exponent-value is an IEEE S-floating complex
    number. For OTS$POWCTCT_R3, complex-exponent-value is an IEEE
    T-floating complex number.

3.24  –  OTS$POWCxJ

    The Raise a Complex Base to a Signed Longword Integer Exponent
    routines return the complex result of raising a complex base to
    an integer exponent.

    Format

      OTS$POWCJ  complex-base ,longword-integer-exponent

      OTS$POWCDJ_R3  complex-base ,longword-integer-exponent (VAX

                     only)

      OTS$POWCGJ_R3  complex-base ,longword-integer-exponent (VAX

                     only)

      OTS$POWCSJ  complex-base ,longword-integer-exponent

      OTS$POWCTJ_R3  complex-base ,longword-integer-exponent

3.24.1  –  Returns

    OpenVMS usage:complex_number
    type:         F_floating complex, D_floating complex, G_floating
                  complex, IEEE S_floating complex, IEEE T_floating
                  complex
    access:       write only
    mechanism:    by value

    Complex result of raising a complex base to an integer exponent.
    OTS$POWCJ returns an F-floating complex number. OTS$POWCDJ_R3
    returns a D-floating complex number. OTS$POWCGJ_R3 returns a G-
    floating complex number. OTS$POWCGS_R3 returns an IEEE S-floating
    complex number. OTS$POWCGT_R3 returns an IEEE T-floating complex
    number. In each format, the result and base are of the same data
    type.

3.24.2  –  Arguments

 complex-base

    OpenVMS usage:complex_number
    type:         F_floating complex, D_floating complex, G_floating
                  complex, S_floating complex, T_floating complex,
    access:       read only
    mechanism:    by value

    Complex base. The complex-base argument contains the complex
    base. For OTS$POWCJ, complex-base is an F-floating complex
    number. For OTS$POWCDJ_R3, complex-base is a D-floating complex
    number. For OTS$POWCGJ_R3, complex-base is a G-floating complex
    number. For OTS$POWCSJ, complex-base is an IEEE S-floating
    complex number. For OTS$POWCTJ_R3, complex-base is an IEEE T-
    floating complex number.

 longword-integer-exponent

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

    Exponent. The longword-integer-exponent argument is a signed
    longword containing the exponent.

3.25  –  OTS$POWDD

    The Raise a D-Floating Base to a D-Floating Exponent routine
    raises a D-floating base to a D-floating exponent.

    Format

      OTS$POWDD  D-floating-point-base ,D-floating-point-exponent

3.25.1  –  Returns

    OpenVMS usage:floating_point
    type:         D_floating
    access:       write only
    mechanism:    by value

    Result of raising a D-floating base to a D-floating exponent.

3.25.2  –  Arguments

 D-floating-point-base

    OpenVMS usage:floating_point
    type:         D_floating
    access:       read only
    mechanism:    by value

    Base. The D-floating-point-base argument is a D-floating number
    containing the base.

 D-floating-point-exponent

    OpenVMS usage:floating_point
    type:         D_floating
    access:       read only
    mechanism:    by value

    Exponent. The D-floating-point-exponent argument is a D-floating
    number that contains the exponent.

3.26  –  OTS$POWDJ

    The Raise a D-Floating Base to a Longword Exponent routine raises
    a D-floating base to a longword exponent.

    Format

      OTS$POWDJ  D-floating-point-base ,longword-integer-exponent

3.26.1  –  Returns

    OpenVMS usage:floating_point
    type:         D_floating
    access:       write only
    mechanism:    by value

    Result of raising a D-floating base to a longword exponent.

3.26.2  –  Arguments

 D-floating-point-base

    OpenVMS usage:floating_point
    type:         D_floating
    access:       read only
    mechanism:    by value

    Base. The D-floating-point-base argument is a D-floating number
    containing the base.

 longword-integer-exponent

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

    Exponent. The longword-integer-exponent argument is a signed
    longword that contains the signed longword integer exponent.

3.27  –  OTS$POWDR

    The Raise a D-Floating Base to an F-Floating Exponent routine
    raises a D-floating base to an F-floating exponent.

    Format

      OTS$POWDR  D-floating-point-base ,F-floating-point-exponent

3.27.1  –  Returns

    OpenVMS usage:floating_point
    type:         D_floating
    access:       write only
    mechanism:    by value

    Result of raising a D-floating base to an F-floating exponent.

3.27.2  –  Arguments

 D-floating-point-base

    OpenVMS usage:floating_point
    type:         D_floating
    access:       read only
    mechanism:    by value

    Base. The D-floating-point-base argument is a D-floating number
    containing the base.

 F-floating-point-exponent

    OpenVMS usage:floating_point
    type:         F_floating
    access:       read only
    mechanism:    by value

    Exponent. The F-floating-point-exponent argument is an F-floating
    number that contains the exponent.

3.28  –  OTS$POWGG

    The Raise a G-Floating Base to a G-Floating Exponent routine
    raises a G-floating base to a G-floating exponent.

    Format

      OTS$POWGG  G-floating-point-base ,G-floating-point-exponent

3.28.1  –  Returns

    OpenVMS usage:floating_point
    type:         G_floating
    access:       write only
    mechanism:    by value

    Result of raising a G-floating base to a G-floating exponent.

3.28.2  –  Arguments

 G-floating-point-base

    OpenVMS usage:floating_point
    type:         G_floating
    access:       read only
    mechanism:    by value

    Base that OTS$POWGG raises to a G-floating exponent. The G-
    floating-point-base argument is a G-floating number containing
    the base.

 G-floating-point-exponent

    OpenVMS usage:floating_point
    type:         G_floating
    access:       read only
    mechanism:    by value

    Exponent to which OTS$POWGG raises the base. The G-floating-
    point-exponent argument is a G-floating number containing the
    exponent.

3.29  –  OTS$POWGJ

    The Raise a G-Floating Base to a Longword Exponent routine raises
    a G-floating base to a longword exponent.

    Format

      OTS$POWGJ  G-floating-point-base ,longword-integer-exponent

3.29.1  –  Returns

    OpenVMS usage:floating_point
    type:         G_floating
    access:       write only
    mechanism:    by value

    Result of raising a G-floating base to a longword exponent.

3.29.2  –  Arguments

 G-floating-point-base

    OpenVMS usage:floating_point
    type:         G_floating
    access:       read only
    mechanism:    by value

    Base that OTS$POWGJ raises to a longword exponent. The G-
    floating-point-base argument is a G-floating number containing
    the base.

 longword-integer-exponent

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

    Exponent to which OTS$POWGJ raises the base. The longword-
    integer-exponent argument is a signed longword containing the
    exponent.

3.30  –  OTS$POWHH_R3

    On VAX systems, the Raise an H-Floating Base to an H-Floating
    Exponent routine raises an H-floating base to an H-floating
    exponent.

    Format

      OTS$POWHH_R3  H-floating-point-base ,H-floating-point-exponent

3.30.1  –  Returns

    OpenVMS usage:floating_point
    type:         H_floating
    access:       write only
    mechanism:    by value

    Result of raising an H-floating base to an H-floating exponent.

3.30.2  –  Arguments

 H-floating-point-base

    OpenVMS usage:floating_point
    type:         H_floating
    access:       read only
    mechanism:    by value

    Base. The H-floating-point-base argument is an H-floating number
    containing the base.

 H-floating-point-exponent

    OpenVMS usage:floating_point
    type:         H_floating
    access:       read only
    mechanism:    by value

    Exponent. The H-floating-point-exponent argument is an H-floating
    number that contains the H-floating exponent.

3.31  –  OTS$POWHJ_R3

    On VAX systems, the Raise an H-Floating Base to a Longword
    Exponent routine raises an H-floating base to a longword
    exponent.

    Format

      OTS$POWHJ_R3  H-floating-point-base ,longword-integer-exponent

3.31.1  –  Returns

    OpenVMS usage:floating_point
    type:         H_floating
    access:       write only
    mechanism:    by value

    Result of raising an H-floating base to a longword exponent.

3.31.2  –  Arguments

 H-floating-point-base

    OpenVMS usage:floating_point
    type:         H_floating
    access:       read only
    mechanism:    by value

    Base. The H-floating-point-base argument is an H-floating number
    containing the base.

 longword-integer-exponent

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

    Exponent. The longword-integer-exponent argument is a signed
    longword that contains the signed longword exponent.

3.32  –  OTS$POWII

    The Raise a Word Base to a Word Exponent routine raises a word
    base to a word exponent.

    Format

      OTS$POWII  word-integer-base ,word-integer-exponent

3.32.1  –  Returns

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       write only
    mechanism:    by value

    Result of raising a word base to a word exponent.

3.32.2  –  Arguments

 word-integer-base

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by value

    Base. The word-integer-base argument is a signed word containing
    the base.

 word-integer-exponent

    OpenVMS usage:word_signed
    type:         word (signed)
    access:       read only
    mechanism:    by value

    Exponent. The word-integer-exponent argument is a signed word
    containing the exponent.

3.33  –  OTS$POWJJ

    The Raise a Longword Base to a Longword Exponent routine raises a
    signed longword base to a signed longword exponent.

    Format

      OTS$POWJJ  longword-integer-base ,longword-integer-exponent

3.33.1  –  Returns

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by value

    Result of raising a signed longword base to a signed longword
    exponent.

3.33.2  –  Arguments

 longword-integer-base

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

    Base. The longword-integer-base argument is a signed longword
    containing the base.

 longword-integer-exponent

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

    Exponent. The longword-integer-exponent argument is a signed
    longword containing the exponent.

3.34  –  OTS$POWLULU

    The Raise an Unsigned Longword Base to an Unsigned Longword
    Exponent routine raises an unsigned longword integer base to
    an unsigned longword integer exponent.

    Format

      OTS$POWLULU  unsigned-lword-int-base,

                   unsigned-lword-int-exponent

3.34.1  –  Returns

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

    Result of raising an unsigned longword integer base to an
    unsigned longword integer exponent.

3.34.2  –  Arguments

 unsigned-lword-int-base

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

    Unsigned longword integer base. The unsigned-lword-int-base
    argument contains the value of the integer base.

 unsigned-lword-int-exponent

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

    Unsigned longword integer exponent. The unsigned-lword-int-
    exponent argument contains the value of the integer exponent.

3.35  –  OTS$POWRD

    The Raise an F-Floating Base to a D-Floating Exponent routine
    raises an F-floating base to a D-floating exponent.

    Format

      OTS$POWRD  F-floating-point-base ,D-floating-point-exponent

3.35.1  –  Returns

    OpenVMS usage:floating_point
    type:         D_floating
    access:       write only
    mechanism:    by value

    Result of raising an F-floating base to a D-floating exponent.

3.35.2  –  Arguments

 F-floating-point-base

    OpenVMS usage:floating_point
    type:         F_floating
    access:       read only
    mechanism:    by value

    Base. The F-floating-point-base argument is an F-floating number
    containing the base.

 D-floating-point-exponent

    OpenVMS usage:floating_point
    type:         D_floating
    access:       read only
    mechanism:    by value

    Exponent. The D-floating-point-exponent argument is a D-floating
    number that contains the exponent.

3.36  –  OTS$POWRJ

    The Raise an F-Floating Base to a Longword Exponent routine
    raises an F-floating base to a longword exponent.

    Format

      OTS$POWRJ  F-floating-point-base ,longword-integer-exponent

3.36.1  –  Returns

    OpenVMS usage:floating_point
    type:         F_floating
    access:       write only
    mechanism:    by value

    Result of raising an F-floating base to a longword exponent.

3.36.2  –  Arguments

 F-floating-point-base

    OpenVMS usage:floating_point
    type:         F_floating
    access:       read only
    mechanism:    by value

    Base. The F-floating-point-base argument is an F-floating number
    containing the base.

 longword-integer-exponent

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

    Exponent. The longword-integer-exponent argument is a signed
    longword that contains the longword exponent.

3.37  –  OTS$POWRR

    The Raise an F-Floating Base to an F-Floating Exponent routine
    raises an F-floating base to an F-floating exponent.

    Format

      OTS$POWRR  F-floating-point-base ,F-floating-point-exponent

3.37.1  –  Returns

    OpenVMS usage:floating_point
    type:         F_floating
    access:       write only
    mechanism:    by value

    Result of raising an F-floating base to an F-floating exponent.

3.37.2  –  Arguments

 F-floating-point-base

    OpenVMS usage:floating_point
    type:         F_floating
    access:       read only
    mechanism:    by value

    Base. The F-floating-point-base argument is an F-floating number
    containing the base.

 F-floating-point-exponent

    OpenVMS usage:floating_point
    type:         F_floating
    access:       read only
    mechanism:    by value

    Exponent. The F-floating-point-exponent argument is an F-floating
    number that contains the exponent.

3.38  –  OTS$POWSJ

    The Raise an IEEE S-Floating Base to a Longword Exponent routine
    raises an IEEE S-floating base to a longword exponent.

    Format

      OTS$POWSJ  S-floating-point-base ,longword-integer-exponent

3.38.1  –  Returns

    OpenVMS usage:floating_point
    type:         S_floating
    access:       write only
    mechanism:    by value

    Result of raising an IEEE S-floating base to a longword exponent.

3.38.2  –  Arguments

 S-floating-point-base

    OpenVMS usage:floating_point
    type:         S_floating
    access:       read only
    mechanism:    by value

    Base. The S-floating-point-base argument is an IEEE S-floating
    number containing the base.

 longword-integer-exponent

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

    Exponent. The longword-integer-exponent argument is a signed
    longword that contains the longword exponent.

3.39  –  OTS$POWSS

    The Raise an IEEE S-Floating Base to an IEEE S-Floating Exponent
    routine raises a IEEE S-floating base to an IEEE S-floating
    exponent.

    Format

      OTS$POWSS  S-floating-point-base ,S-floating-point-exponent

3.39.1  –  Returns

    OpenVMS usage:floating_point
    type:         IEEE S_floating
    access:       write only
    mechanism:    by value

    Result of raising an IEEE S-floating base to an IEEE S-floating
    exponent.

3.39.2  –  Arguments

 S-floating-point-base

    OpenVMS usage:floating_point
    type:         IEEE S_floating
    access:        read only
    mechanism:    by value

    Base that OTS$POWSS raises to an IEEE S-floating exponent. The
    S-floating-point-base argument is an IEEE S-floating number
    containing the base.

 S-floating-point-exponent

    OpenVMS usage:floating_point
    type:         IEEE S_floating
    access:        read only
    mechanism:    by value

    Exponent to which OTS$POWSS raises the base. The S-floating-
    point-exponent argument is an IEEE S-floating number containing
    the exponent.

3.40  –  OTS$POWTJ

    The Raise a T-Floating base to a Longword Exponent routine raises
    an IEEE T-floating base to a longword exponent.

    Format

      OTS$POWTJ  T-floating-point-base ,longword-integer-exponent

3.40.1  –  Returns

    OpenVMS usage:floating_point
    type:         IEEE T_floating
    access:       write only
    mechanism:    by value

    Result of raising an IEEE T-floating base to a longword exponent.

3.40.2  –  Arguments

 T-floating-point-base

    OpenVMS usage:floating_point
    type:         IEEE T_floating
    access:       read only
    mechanism:    by value

    Base. The T-floating-point-base argument is an IEEE T-floating
    number containing the base.

 longword-integer-exponent

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

    Exponent. The longword-integer-exponent argument is a signed
    longword that contains the longword exponent.

3.41  –  OTS$POWTT

    The Raise an IEEE T-Floating Base to an IEEE T-Floating Exponent
    routine raises an IEEE T-floating base to an IEEE T-floating
    exponent.

    Format

      OTS$POWTT  T-floating-point-base ,T-floating-point-exponent

3.41.1  –  Returns

    OpenVMS usage:floating_point
    type:         IEEE T_floating
    access:       write only
    mechanism:    by value

    Result of raising an IEEE T-floating base to an IEEE T-floating
    exponent.

3.41.2  –  Arguments

 T-floating-point-base

    OpenVMS usage:floating_point
    type:         IEEE T_floating
    access:       read only
    mechanism:    by value

    Base that OTS$POWTT raises to an IEEE T-floating exponent. The
    T-floating-point-base argument is an IEEE T-floating number
    containing the base.

 T-floating-point-exponent

    OpenVMS usage:floating_point
    type:         IEEE T_floating
    access:       read only
    mechanism:    by value

    Exponent to which OTS$POWTT raises the base. The T-floating-
    point-exponent argument is an IEEE T-floating number containing
    the exponent.

3.42  –  OTS$POWxLU

    The Raise a Floating-Point Base to an Unsigned Longword Integer
    Exponent routines raise a floating-point base to an unsigned
    longword integer exponent.

    Format

      OTS$POWRLU  floating-point-base ,unsigned-lword-int-exponent

      OTS$POWDLU  floating-point-base ,unsigned-lword-int-exponent

      OTS$POWGLU  floating-point-base ,unsigned-lword-int-exponent

      OTS$POWSLU  floating-point-base ,unsigned-lword-int-exponent

      OTS$POWTLU  floating-point-base ,unsigned-lword-int-exponent

      OTS$POWHLU_R3  floating-point-base ,unsigned-lword-int-exponent

                     (VAX only)

3.42.1  –  Returns

    OpenVMS usage:floating_point
    type:         F_floating, D_floating, G_floating, H_floating,
                  IEEE S_floating, IEEE T_floating
    access:       write only
    mechanism:    by value

    Result of raising a floating-point base to an unsigned longword
    integer exponent. OTS$POWRLU returns an F-floating number.
    OTS$POWDLU returns a D-floating number. OTS$POWGLU returns a
    G-floating number. OTS$POWSLU returns an IEEE S-floating number.
    OTS$POWTLU returns an IEEE T-floating number.

    On VAX systems, OTS$POWHLU_R3 returns an H-floating number.

3.42.2  –  Arguments

 floating-point-base

    OpenVMS usage:floating_point
    type:         F_floating, D_floating, G_floating, H_floating,
                  IEEE S_floating, IEEE T_floating
    access:       read only
    mechanism:    by value

    Floating-point base. The floating-point-base argument contains
    the value of the base. For OTS$POWRLU, floating-point-base is
    an F-floating number. For OTS$POWDLU, floating-point-base is a
    D-floating number. For OTS$POWGLU, floating-point-base is a G-
    floating number. For OTS$POWHLU_R3, floating-point-base is an
    H-floating number. For OTS$POWSLU, floating-point-base is an IEE
    S-floating number. For OTS$POWTLU, floating-point-base is an IEEE
    T-floating number.

 unsigned-lword-int-exponent

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

    Integer exponent. The unsigned-lword-int-exponent argument
    contains the value of the unsigned longword integer exponent.

3.43  –  OTS$SCOPY_DXDX

    The Copy a Source String Passed by Descriptor to a Destination
    String routine copies a source string to a destination string.
    Both strings are passed by descriptor.

    Format

      OTS$SCOPY_DXDX  source-string ,destination-string

3.43.1  –  Corresponding JSB Entry Point

      OTS$SCOPY_DXDX6

3.43.2  –  Returns

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by value

    Number of bytes not moved to the destination string if the length
    of source-string is greater than the length of destination-
    string. The value is 0 (zero) otherwise.

3.43.3  –  Arguments

 source-string

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

    Source string. The source-string argument is the address of a
    descriptor pointing to the source string. The descriptor class
    can be unspecified, fixed length, dynamic, scalar decimal, array,
    noncontiguous array, or varying.

 destination-string

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

    Destination string. The destination-string argument is the
    address of a descriptor pointing to the destination string. The
    class field determines the appropriate action.

3.44  –  OTS$SCOPY_R_DX

    The Copy a Source String Passed by Reference to a Destination
    String routine copies a source string passed by reference to a
    destination string.

    Format

      OTS$SCOPY_R_DX  word-int-source-length-val

                      ,source-string-address ,destination-string

3.44.1  –  Corresponding JSB Entry Point

      OTS$SCOPY_R_DX6

3.44.2  –  Returns

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by value

    Number of bytes not moved to the destination string if the length
    of the source string pointed to by source-string-address is
    greater than the length of destination-string. Otherwise, the
    value is 0 (zero).

3.44.3  –  Arguments

 word-int-source-length-val

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by value

    Length of the source string. The word-int-source-length-val
    argument is an unsigned word integer containing the length of
    the source string.

 source-string-address

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

    Source string. The source-string-address argument is the address
    of the source string.

 destination-string

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

    Destination string. The destination-string argument is the
    address of a descriptor pointing to the destination string.
    OTS$SCOPY_R_DX determines the appropriate action based on the
    descriptor's CLASS field. The descriptor's LENGTH field alone or
    both the POINTER and LENGTH fields can be modified if the string
    is dynamic. For varying strings, the string's current length
    (CURLEN) is rewritten.

3.45  –  OTS$SFREE1_DD

    The Strings, Free One Dynamic routine returns one dynamic string
    area to free storage.

    Format

      OTS$SFREE1_DD  dynamic-descriptor

3.45.1  –  Corresponding JSB Entry Point

      OTS$SFREE1_DD6

3.45.2  –  Returns

    None.

3.45.3  –  Argument

 dynamic-descriptor

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by reference

    Dynamic string descriptor. The dynamic-descriptor argument is
    the address of the dynamic string descriptor. The descriptor is
    assumed to be dynamic and its class field is not checked.

3.46  –  OTS$SFREEN_DD

    The Free n Dynamic Strings routine takes as input a vector of one
    or more dynamic string areas and returns them to free storage.

    Format

      OTS$SFREEN_DD  descriptor-count-value ,first-descriptor

3.46.1  –  Corresponding JSB Entry Point

      OTS$SFREEN_DD6

3.46.2  –  Returns

    None.

3.46.3  –  Arguments

 descriptor-count-value

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

    Number of adjacent descriptors to be flagged as having no
    allocated area (the descriptor's POINTER and LENGTH fields
    contain 0) and to have their allocated areas returned to free
    storage by OTS$SFREEN_DD. The descriptor-count-value argument is
    an unsigned longword containing this number.

 first-descriptor

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by reference

    First string descriptor of an array of string descriptors. The
    first-descriptor argument is the address of the first string
    descriptor. The descriptors are assumed to be dynamic, and their
    class fields are not checked.

3.47  –  OTS$SGET1_DD

    The Get One Dynamic String routine allocates a specified
    number of bytes of dynamic virtual memory to a specified string
    descriptor.

    Format

      OTS$SGET1_DD  word-integer-length-value ,dynamic-descriptor

3.47.1  –  Corresponding JSB Entry Point

      OTS$SGET1_DD_R6

3.47.2  –  Returns

    None.

3.47.3  –  Arguments

 word-integer-length-value

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by value

    Number of bytes to be allocated. The word-integer-length-value
    argument contains the number of bytes. The amount of storage
    allocated is automatically rounded up. If the number of bytes is
    zero, a small number of bytes is allocated.

 dynamic-descriptor

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       modify
    mechanism:    by reference

    Dynamic string descriptor to which the area is to be allocated.
    The dyn-str argument is the address of the dynamic string
    descriptor. The CLASS field is not checked but it is set to
    dynamic (CLASS = 2). The LENGTH field is set to word-integer-
    length-value and the POINTER field is set to the string area
    allocated (first byte beyond the header).

4  –  PPL$

4.1  –  PPL$ADJUST_QUORUM

    The Adjust Barrier Quorum routine increments or decrements the
    quorum associated with a barrier.

    Format

      PPL$ADJUST_QUORUM  barrier-id ,amount

4.1.1  –  Arguments

 barrier-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the barrier. The barrier-id argument is the address
    of an unsigned longword containing the barrier identifier.

    Barrier-id is returned by PPL$CREATE_BARRIER.

 amount

    OpenVMS usage word_signed
    type          word (signed)
    access        read only
    mechanism     by reference
    Value to add to the barrier quorum. The amount argument is the
    address of a signed word containing the amount. You can specify a
    negative value to decrement the quorum.

4.2  –  PPL$ADJUST_SEMAPHORE_MAXIMUM

    The Adjust a Semaphore Maximum routine increments or decrements
    the maximum associated with a semaphore.

    Format

      PPL$ADJUST_SEMAPHORE_MAXIMUM  semaphore-id ,amount

4.2.1  –  Arguments

 semaphore-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the semaphore. The semaphore-id argument is the
    address of an unsigned longword containing the identifier.

 amount

    OpenVMS usage word_signed
    type          word (signed)
    access        read only
    mechanism     by reference
    Value to add to the semaphore maximum. The amount argument is
    the address of a signed word containing the amount. Specify a
    positive value for amount to increase the maximum; specify a
    negative value to decrease the maximum.

4.3  –  PPL$AWAIT_EVENT

    The Await Event Occurrence routine blocks the caller until an
    event occurs.

    Format

      PPL$AWAIT_EVENT  event-id [,output]

4.3.1  –  Arguments

 event-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the event. The event-id argument is the address of
    an unsigned longword containing the identifier.

    The event-id is returned by PPL$CREATE_EVENT.

 output

    OpenVMS usage user_arg
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Receives the event-param argument from PPL$TRIGGER_EVENT. The
    output argument is the address of an unsigned longword that
    receives the value of event-param. The value of event-param is
    copied to output when an event is triggered.

4.4  –  PPL$CREATE_APPLICATION

    The Form or Join a PPL$ Application routine informs the PPL$
    facility that the calling process is forming or joining a
    parallel application.

    Format

      PPL$CREATE_APPLICATION  [size] [,application-name]

                              [,protection] [,flags]

4.4.1  –  Arguments

 size

    OpenVMS usage longword_unsigned
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Number of (512 byte) pages that PPL$ allocates for its internal
    data structures. The optional size argument is the address of an
    unsigned longword containing this size value. See the Description
    section for information about the default value.

 application-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    The name of the application that the calling process will form or
    join. The optional application-name argument is the address of a
    descriptor pointing to a character string containing the name of
    the application. The application-name argument can contain up to
    11 characters.

 protection

    OpenVMS usage file_protection
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Numeric value representing the protection mask to be applied to
    the application. The optional protection argument is the address
    of an unsigned longword containing this numeric value. For more
    information, see the description of the $CRMPSC system service in
    the OpenVMS System Services Reference Manual.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Specifies options for forming or joining a PPL$ application. The
    flags argument is a longword bit mask containing the flags. Valid
    values for flags are as follows:

    PPL$M_         Form a new application only-do not join an
    FORMONLY       existing application. If this flag is not
                   specified, a process will join an application
                   if it already exists.
    PPL$M_         Join an existing application only-do not form a
    JOINONLY       new application. If this flag is not specified,
                   a process will form an application if it does not
                   already exist.
    PPL$M_PERM     Form a permanent application in which data is
                   maintained even though there are no active
                   processes. By default, application data is lost
                   when the last process in the application exits.
                   Use of this flag requires PRMGBL privilege.
    PPL$M_SYSTEM   Form or join a systemwide application. By default,
                   the application is available only to processes
                   running under the same group UIC. Use of this flag
                   requires SYSGBL and SYSLCK privileges.

4.5  –  PPL$CREATE_BARRIER

    The Create a Barrier routine creates and initializes a barrier,
    and returns the barrier identifier. You use the barrier
    identifier to perform all operations on that barrier.

    Format

      PPL$CREATE_BARRIER  barrier-id [,barrier-name] [,quorum]

4.5.1  –  Arguments

 barrier-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Identifier of the barrier. The barrier-id argument is the address
    of an unsigned longword containing the identifier. Barrier-id
    must be used in calls to the other barrier routines (listed in
    the Description section) to identify the barrier.

 barrier-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the barrier. The optional barrier-name argument is the
    address of a descriptor pointing to a character string containing
    the barrier name. The name of the barrier is arbitrary. If you
    do not specify this argument, or if you specify 0, an unnamed
    barrier is created. An arbitrary number of unnamed barriers may
    be created by a given application.

 quorum

    OpenVMS usage word_signed
    type          word (signed)
    access        read only
    mechanism     by reference
    Number of participants required to terminate an active wait for
    this barrier. The quorum argument is the address of a signed
    word containing the quorum number. For example, a quorum value
    of 3 indicates that the first two callers of PPL$WAIT_AT_BARRIER
    specifying this barrier-id are blocked until a third caller calls
    PPL$WAIT_AT_BARRIER. At that point, all three participants are
    released for further processing. If you do not specify a value
    for quorum, a default value of 1 is assigned.

4.6  –  PPL$CREATE_EVENT

    The Create an Event routine creates an arbitrary user-defined
    event and returns the event identifier. You use the event
    identifier to perform all operations on that event.

    Format

      PPL$CREATE_EVENT  event-id [,event-name]

4.6.1  –  Arguments

 event-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Identifier of the event. The event-id argument is the address of
    an unsigned longword containing the identifier. Event-id must be
    used in other calls to identify the event.

 event-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the event. The event-name argument is the address of a
    descriptor pointing to a character string containing the event
    name. The name of the event is entirely arbitrary. If you do
    not specify a value for event-name, or if you specify 0, a new
    unnamed event is created, which can be referenced only by its
    identifier. An arbitrary number of unnamed events can be created
    by a given application.

4.7  –  PPL$CREATE_SEMAPHORE

    The Create a Semaphore routine creates and initializes a
    semaphore with a waiting queue, and returns the semaphore
    identifier. You use the semaphore identifier to perform all
    operations on that semaphore.

    Format

      PPL$CREATE_SEMAPHORE  semaphore-id [,semaphore-name]

                            [,semaphore-maximum] [,semaphore-initial]

4.7.1  –  Arguments

 semaphore-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Identifier of the semaphore. The semaphore-id argument is the
    address of an unsigned longword containing the identifier.
    Semaphore-id must be used in other calls to identify the
    semaphore.

 semaphore-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the semaphore. The semaphore-name argument is the address
    of a descriptor pointing to a character string containing
    the semaphore name. The name of the semaphore is entirely
    arbitrary. If you do not specify a value for semaphore-name,
    or if you specify 0, a new unnamed semaphore is created. An
    arbitrary number of unnamed semaphores may be created by a given
    application.

 semaphore-maximum

    OpenVMS usage word_signed
    type          word (signed)
    access        read only
    mechanism     by reference
    Maximum value of the semaphore. The semaphore-maximum argument
    is the address of a signed word containing the maximum value.
    This value must be nonnegative. If you do not supply a value for
    semaphore-maximum, a default value of 1 is used, thereby making
    it a binary semaphore.

 semaphore-initial

    OpenVMS usage word_signed
    type          word (signed)
    access        read only
    mechanism     by reference
    Initial value of the semaphore. The semaphore-initial argument is
    the address of a signed word containing the initial value. This
    value must be less than or equal to the semaphore-maximum value.
    If you do not supply a value for semaphore-initial, a default
    value equal to semaphore-maximum is used.

4.8  –  PPL$CREATE_SHARED_MEMORY

    The Create Shared Memory routine creates (if necessary) and maps
    a section of memory that can be shared by multiple processes.

    Format

      PPL$CREATE_SHARED_MEMORY  section-name ,memory-area [,flags]

                                [,file-name] [,protection]

4.8.1  –  Arguments

 section-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the shared memory section you want to create. The
    section-name argument is the address of a descriptor pointing
    to the shared memory section name.

 memory-area

    OpenVMS usage vector_longword_unsigned
    type          longword (unsigned)
    access        modify
    mechanism     by reference, array reference
    The area of memory into which the shared memory is mapped. The
    memory-area argument is the address of a two-longword array
    containing, in order, the length (in bytes) and the starting
    virtual address for the area of memory.

    If you specify the starting address as zero, the PPL$ facility
    selects the virtual address space so that each current process
    in the application can map the section to the same set of virtual
    addresses.

    PPL$CREATE_SHARED_MEMORY returns to this argument the actual
    length and starting virtual address of the shared memory created
    or mapped.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Specifies options for creating and mapping shared memory. The
    flags argument is the address of a longword bit mask containing
    the flag. Valid values are as follows:

    PPL$M_NOZERO  Does not initialize the shared memory to zero. By
                  default, PPL$CREATE_SHARED_MEMORY initializes the
                  shared memory to zero.
    PPL$M_NOWRT   Maps the shared memory with no write access (in
                  other words, read only). By default, the shared
                  memory is available with read/write access.
    PPL$M_NOUNI   Names the shared memory a nonunique name. By
                  default, PPL$CREATE_SHARED_MEMORY gives the
                  specified shared memory a name unique to the
                  application by using PPL$UNIQUE_NAME.
    PPL$M_PERM    Creates permanent shared memory in which data
                  is maintained even though there are no active
                  processes. The default is determined by your
                  call to PPL$CREATE_APPLICATION: if you specify
                  the PPL$M_PERM flag in your call to PPL$CREATE_
                  APPLICATION, this behavior is the default and
                  you do not need to specify PPL$M_PERM in your
                  call to PPL$CREATE_SHARED_MEMORY. If you do not
                  specify the PPL$M_PERM flag in your calls to
                  PPL$CREATE_APPLICATION and PPL$CREATE_SHARED_
                  MEMORY, application data is lost when the last
                  process in the application exits. Use of this flag
                  requires PRMGBL privilege.
    PPL$M_SYSTEM  Creates systemwide shared memory. The default is
                  determined by your call to PPL$CREATE_APPLICATION:
                  if you specify the PPL$M_SYSTEM flag in your call
                  to PPL$CREATE_APPLICATION, this behavior is the
                  default and you do not need to specify PPL$M_
                  SYSTEM in your call to PPL$CREATE_SHARED_MEMORY.
                  If you do not specify the PPL$M_SYSTEM flag in your
                  calls to PPL$CREATE_APPLICATION and PPL$CREATE_
                  SHARED_MEMORY, the application is available only to
                  processes running under the same group UIC. Use of
                  this flag requires the SYSGBL privilege.

 file-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the file used for backup storage of the shared memory.
    The file-name argument is the address of a descriptor pointing
    to the file name. The size of the resulting address space is the
    smaller of the following:

    o  The specified section size

    o  The size of the file being mapped

    If you do not specify a file name, PPL$CREATE_SHARED_MEMORY
    creates for backup storage a page file section instead of a disk
    file section.

    If you specify a file that does not exist, PPL$CREATE_SHARED_
    MEMORY creates it.

 protection

    OpenVMS usage file_protection
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Numeric value representing the protection mask to be applied
    to the shared memory. The optional protection argument is the
    address of an unsigned longword containing this numeric value.
    If you do not specify a value, the default is the value for
    protection specified in the call to PPL$CREATE_APPLICATION.
    For more information, see the description of the $CRMPSC system
    service in the OpenVMS System Services Reference Manual.

4.9  –  PPL$CREATE_SPIN_LOCK

    The Create Spin Lock routine creates and initializes a simple
    (spin) lock, and returns the lock identifier. You use that lock
    identifier to get and free the lock.

    Format

      PPL$CREATE_SPIN_LOCK  lock-id [,lock-name]

4.9.1  –  Arguments

 lock-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Identifier of the newly created lock. The lock-id argument is the
    address of an unsigned longword containing the lock identifier.
    You must use lock-id when getting or freeing the lock.

 lock-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the lock. The lock-name argument is the address of a
    descriptor pointing to a character string containing the name.
    The name of the lock is entirely arbitrary. If you do not specify
    this argument, or if you specify 0, an unnamed lock is created.
    An arbitrary number of unnamed locks can be created by a given
    application.

4.10  –  PPL$CREATE_VM_ZONE

    The Create a New Virtual Memory Zone routine creates a new
    storage zone, according to specified arguments, which is
    available to all participants in the application.

    Format

      PPL$CREATE_VM_ZONE  zone-id [,algorithm] [,algorithm-argument]

                          [,flags] [,extend-size] [,initial-size]

                          [,block-size] [,alignment] [,page-limit]

                          [,smallest-block-size] [,zone-name]

4.10.1  –  Arguments

 zone-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Zone identifier. The zone-id argument is the address of a
    longword set to the zone identifier of the newly created zone.

 algorithm

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Algorithm. The algorithm argument is the address of a signed
    longword that represents the code for one of the LIB$VM
    algorithms:

       1   LIB$K_VM_FIRST_   First fit
           FIT
       2   LIB$K_VM_QUICK_   Quick fit, lookaside list
           FIT
       3   LIB$K_VM_FREQ_    Frequent sizes, lookaside list
           SIZES
       4   LIB$K_VM_FIXED    Fixed size blocks

    If algorithm is not specified, a default of 1 (first fit) is
    used.

 algorithm-argument

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Algorithm argument. The algorithm-argument argument is the
    address of a signed longword that contains a value specific to
    the particular allocation algorithm.

    Algorithm   Value

    QUICK_FIT   The number of queues used. The number of queues must
                be between 1 and 128.
    FREQ_SIZES  The number of cache slots used. The number of cache
                slots must be between 1 and 16.
    FIXED       The fixed request size (in bytes) for each get or
                free. The request size must be greater than 0.
    FIRST_FIT   Not used, may be omitted.

    The algorithm-argument argument must be specified if you are
    using the quick-fit, frequent-sizes, or fixed-size-blocks
    algorithms. However, this argument is optional if you are using
    the first-fit algorithm.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Flags. The flags argument is the address of an unsigned longword
    that contains flag bits that control various options:

    Bit   Value                 Description

    Bit   LIB$M_VM_BOUNDARY_    Boundary tags for faster freeing
    0     TAGS
                                Adds a minimum of eight bytes to each
                                block
    Bit   LIB$M_VM_GET_FILL0    LIB$GET_VM; fill with bytes of 0
    1
    Bit   LIB$M_VM_GET_FILL1    LIB$GET_VM; fill with bytes of FF
    2                           (hexadecimal)
    Bit   LIB$M_VM_FREE_FILL0   LIB$FREE_VM; fill with bytes of 0
    3
    Bit   LIB$M_VM_FREE_FILL1   LIB$FREE_VM; fill with bytes of FF
    4                           (hexadecimal)
    Bit   LIB$M_VM_EXTEND_      Add extents to existing areas if
    5     AREA                  possible

    Bits 6 through 31 are reserved and must be 0.

    This is an optional argument. If flags is omitted, the default of
    0 (no fill and no boundary tags) is used.

 extend-size

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Zone extend size. The extend-size argument is the address of a
    signed longword that contains the number of (512-byte) pages to
    be added to the zone each time it is extended.

    The value of extend-size must be between 1 and 1024.

    This is an optional argument. If extend-size is not specified, a
    default of 16 pages is used.

                                   NOTE

       Extend-size does not limit the number of blocks that can be
       allocated from the zone. The actual extension size is the
       greater of extend-size and the number of pages needed to
       satisfy the LIB$GET_VM call that caused the extend.

 initial-size

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Initial size for the zone. The initial-size argument is the
    address of a signed longword that contains the number of (512-
    byte) pages to be allocated for the zone as the zone is created.

    This is an optional argument. If initial-size is not specified
    or is specified as 0, no pages are allocated when the zone is
    created. The first call to LIB$GET_VM for the zone allocates
    extend-size pages.

 block-size

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Block size of the zone. The block-size argument is the address
    of a signed longword specifying the allocation quantum (in bytes)
    for the zone. All blocks allocated are rounded up to a multiple
    of block-size.

    The value of block-size must be a power of 2 between 8 and 512.
    This is an optional argument. If block-size is not specified, a
    default of 8 is used.

 alignment

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Block alignment. The alignment argument is the address of a
    signed longword that specifies the required address alignment
    (in bytes) for each block allocated.

    The value of alignment must be a power of 2 between 4 and 512.
    This is an optional argument. If alignment is not specified, a
    default of 8 (quadword alignment) is used.

 page-limit

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Maximum page limit. The page-limit argument is the address of a
    signed longword that specifies the maximum number of (512-byte)
    pages that can be allocated for the zone. The value of page-limit
    must be between 0 and 32,767. Note that part of the zone is used
    for header information.

    This is an optional argument. If page-limit is not specified or
    is specified as 0, the only limit is the total process virtual
    address space limit imposed by the OpenVMS operating system.
    If page-limit is specified, then initial-size must also be
    specified.

 smallest-block-size

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Smallest block size. The smallest-block-size argument is the
    address of a signed longword that specifies the smallest block
    size (in bytes) with a queue for the quick fit algorithm.

    If smallest-block-size is not specified, the default of block-
    size is used. That is, queues are provided for the first n
    multiples of block-size.

 zone-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name to be associated with the zone being created. The optional
    zone-name argument is the address of a descriptor pointing to a
    character string containing the zone name. If zone-name is not
    specified, the zone does not have an associated name.

4.11  –  PPL$CREATE_WORK_QUEUE

    The Create a Work Queue routine creates and initializes a work
    queue and returns the work queue identifier.

    Format

      PPL$CREATE_WORK_QUEUE  queue-id [,queue-name]

4.11.1  –  Arguments

 queue-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    The work queue identifier. The queue-id argument is the address
    of an unsigned longword containing the identifier. Queue-id must
    be used in calls to the other work queue routines to identify the
    work queue.

 queue-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the work queue. The optional queue-name argument is the
    address of a descriptor pointing to a character string containing
    the work queue name. The work queue name is case sensitive. If
    you do not specify this argument, or if you specify 0, an unnamed
    work queue is created. An arbitrary number of unnamed work queues
    may be created by a given application.

4.12  –  PPL$DECREMENT_SEMAPHORE

    The Decrement a Semaphore routine waits for a semaphore to have a
    value greater than 0, then decrements the value by 1 to indicate
    the allocation of a resource.

    Format

      PPL$DECREMENT_SEMAPHORE  semaphore-id [,flags] [,spin]

4.12.1  –  Arguments

 semaphore-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the semaphore. The semaphore-id argument is the
    address of an unsigned longword containing the identifier.

    Semaphore-id is returned by PPL$CREATE_SEMAPHORE.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Bit mask specifying options for decrementing the semaphore. The
    flags argument is a longword bit mask containing the flag. The
    valid values for flags are as follows:

    PPL$M_NON_         Indicates that the caller is not to block if
    BLOCKING           the resource is not available. The default is
                       FALSE: the caller will block if resource is
                       unavailable.
    PPL$M_SPIN_WAIT    Indicates that the caller is never to block,
                       but rather to always spin while waiting at
                       this barrier.
    PPL$M_SPIN_        Indicates that the caller wishes to spin for
    COUNTED            a given amount of instructions and then to
                       block. The default is block immediately, do
                       not spin at all.

 spin

    OpenVMS usage mask_longword
    type          long (unsigned)
    access        read only
    mechanism     by reference
    This value must be specified when using the PPL$M_SPIN_COUNTED
    flag and represents a relative time that a process will spin
    before blocking.

4.13  –  PPL$DELETE_APPLICATION

    The Delete a PPL$ Application routine marks all shared memory
    for deletion and prevents additional processes from joining the
    application.

    Format

      PPL$DELETE_APPLICATION

4.14  –  PPL$DELETE_BARRIER

    The Delete a Barrier routine deletes a barrier and releases any
    storage associated with it.

    Format

      PPL$DELETE_BARRIER  [barrier-id] [,barrier-name]

4.14.1  –  Arguments

 barrier-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the barrier. The optional barrier-id argument
    is the address of an unsigned longword containing the barrier
    identifier.

 barrier-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the barrier. The optional barrier-name argument is the
    address of a descriptor pointing to a character string containing
    the barrier name.

4.15  –  PPL$DELETE_EVENT

    The Delete an Event routine deletes an event and releases any
    storage associated with it.

    Format

      PPL$DELETE_EVENT  [event-id] [,event-name]

4.15.1  –  Arguments

 event-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the event. The optional event-id argument is the
    address of an unsigned longword containing the event identifier.

 event-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the event. The optional event-name argument is the
    address of a descriptor pointing to a character string containing
    the event name.

4.16  –  PPL$DELETE_SEMAPHORE

    The Delete a Semaphore routine deletes a semaphore and releases
    any storage associated with it.

    Format

      PPL$DELETE_SEMAPHORE  [semaphore-id] [,semaphore-name]

4.16.1  –  Arguments

 semaphore-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the semaphore. The optional semaphore-id argument
    is the address of an unsigned longword containing the semaphore
    identifier.

 semaphore-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the semaphore. The optional semaphore-name argument
    is the address of a descriptor pointing to a character string
    containing the semaphore name.

4.17  –  PPL$DELETE_SHARED_MEMORY

    The Delete Shared Memory routine deletes or unmaps from a global
    section that you created using the PPL$CREATE_SHARED_MEMORY
    routine. Optionally, this routine writes the contents of the
    global section to disk before deleting the section.

    Format

      PPL$DELETE_SHARED_MEMORY  section-name [,memory-area] [,flags]

4.17.1  –  Arguments

 section-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the global section you want to delete. The section-name
    argument is the address of a descriptor pointing to a character
    string containing the global section name.

 memory-area

    OpenVMS usage vector_longword_unsigned
    type          longword (unsigned)
    access        read only
    mechanism     by reference, array reference
    The area of memory into which the global section that you want
    to delete is mapped. The memory-area argument is the address of a
    two-longword array containing, in order, the length in bytes and
    the starting virtual address of the area of memory.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Bit mask specifying actions to be performed before deleting the
    global section. The flags argument is the address of a longword
    bit mask containing the flag. Valid values for flags are as
    follows:

    PPL$M_FLUSH     Writes the global section to disk before deleting
                    it.
    PPL$M_NOUNI     Identifies the global section as having a
                    nonunique name. By default, PPL$CREATE_SHARED_
                    MEMORY gives the specified global section a name
                    unique to the application by using PPL$UNIQUE_
                    NAME. If you specified this value to give the
                    global section a nonunique name when you called
                    PPL$CREATE_SHARED_MEMORY, you must also specify
                    it when you call PPL$DELETE_SHARED_MEMORY.

4.18  –  PPL$DELETE_SPIN_LOCK

    The Delete a Spin Lock routine deletes a spin lock and releases
    any storage associated with it.

    Format

      PPL$DELETE_SPIN_LOCK  [lock-id] [,lock-name]

4.18.1  –  Arguments

 lock-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the lock. The optional lock-id argument is the
    address of an unsigned longword containing the lock identifier.

 lock-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the lock. The optional lock-name argument is the address
    of a descriptor pointing to a character string containing the
    lock name.

4.19  –  PPL$DELETE_VM_ZONE

    The Delete a Virtual Memory Zone routine deletes a storage zone
    and returns all pages owned by the zone to the application-wide
    page pool.

    Format

      PPL$DELETE_VM_ZONE  [zone-id] [,zone-name]

4.19.1  –  Arguments

 zone-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the zone. The optional zone-id argument is the
    address of an unsigned longword containing the zone identifier.

 zone-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the zone. The optional zone-name argument is the address
    of a descriptor pointing to a character string containing the
    zone name.

4.20  –  PPL$DELETE_WORK_ITEM

    The Delete a Work Queue Item routine deletes a work item from a
    work queue.

    Format

      PPL$DELETE_WORK_ITEM  queue-id ,work-item [,flags]

4.20.1  –  Arguments

 queue-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    The queue identifier. The queue-id argument is the address of an
    unsigned longword containing the identifier.

 work-item

    OpenVMS usage user_arg
    type          longword (unsigned)
    access        read only
    mechanism     by value
    The value of the item to be deleted from the queue. The work-item
    argument is the address of an unsigned longword containing this
    value.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Specifies options for deleting items from a work queue. The
    optional flags argument is the address of a longword bit mask
    containing the flag. Valid values are as follows:

    PPL$M_DELETEALL    Delete all items in the specified queue whose
                       value matches work-item. By default, only the
                       first item encountered is deleted.
    PPL$M_TAILFIRST    Begin searching at the end of the queue and
                       move toward the beginning. By default, the
                       search begins at the beginning of the queue
                       and moves toward the end.

4.21  –  PPL$DELETE_WORK_QUEUE

    The Delete a Work Queue routine deletes the specified work queue,
    and releases any storage associated with it.

    Format

      PPL$DELETE_WORK_QUEUE  [queue-id] [,queue-name] [,flags]

4.21.1  –  Arguments

 queue-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    The work queue identifier. The optional queue-id argument is the
    address of an unsigned longword containing the identifier.

 queue-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the work queue. The optional queue-name argument is the
    address of a descriptor pointing to a character string containing
    the work queue name.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Specifies options for deleting a work queue. The optional flags
    argument is the address of a longword bit mask containing the
    flag. The valid value is as follows:

    PPL$M_FORCEDEL   Delete the work queue regardless of whether it
                     is empty. By default, PPL$ returns the error
                     PPL$_ELEINUSE if you attempt to delete a work
                     queue at which proceses are blocked or that
                     contains work items.

4.22  –  PPL$DISABLE_EVENT

    The Disable Asynchronous Notification of an Event routine
    disables delivery to a process of notification of an event by
    either AST or signal.

    Format

      PPL$DISABLE_EVENT  event-id

4.22.1  –  Arguments

 event-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the event. The event-id argument is the address of
    an unsigned longword containing the identifier.

4.23  –  PPL$ENABLE_EVENT_AST

    The Enable AST Notification of an Event routine specifies the
    address of an AST routine (and optionally an argument to that
    routine) to be delivered when an event occurs.

    Format

      PPL$ENABLE_EVENT_AST  event-id ,astadr [,astprm]

4.23.1  –  Arguments

 event-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the event. The event-id argument is the address of
    an unsigned longword containing the identifier.

    Event-id is returned by PPL$CREATE_EVENT.

 astadr

    OpenVMS usage ast_procedure
    type          procedure value
    access        call without stack unwinding
    mechanism     by reference
    AST routine. The astadr argument is a procedure value of the
    user's AST routine. This routine is called on the user's behalf
    when the event state becomes occurred.

 astprm

    OpenVMS usage user_arg
    type          unspecified
    access        read only
    mechanism     by value
    AST value passed as the argument to the specified AST routine.
    The astprm argument is the address of a vector of unsigned
    longwords containing this optional value. If this argument is not
    specified, PPL$_EVENT_OCCURRED is the astprm for a user-created
    event. The astprm argument has special restrictions when used in
    conjunction with the PPL$ event routines.

    o  For user-defined events, the AST-argument must point to a
       vector of two unsigned longwords. The first longword is a
       "context" reserved for the user; it is not read or modified
       by PPL$. The second longword receives the value specified by
       the event-param argument in the call to PPL$TRIGGER_EVENT that
       results in the delivery of this AST.

    o  For PPL$-defined events (those not created by the user),
       the astprm argument must point to a vector of four unsigned
       longwords. The vector accommodates the following:

       -  The user's "context" longword

       -  The longword to receive the event's distinguishing
          condition value

       -  The parameters to the PPL$-defined event (the "trigger"
          parameter)

       Because each of the predefined events takes two arguments, the
       vector that astprm points to must be four longwords in length.

4.24  –  PPL$ENABLE_EVENT_SIGNAL

    The Enable Signal Notification of an Event routine specifies a
    condition value to be signaled when the event occurs.

    Format

      PPL$ENABLE_EVENT_SIGNAL  event-id [,signal-value]

4.24.1  –  Arguments

 event-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the event. The event-id argument is the address of
    an unsigned longword containing the identifier.

    Event-id is returned by PPL$CREATE_EVENT.

 signal-value

    OpenVMS usage user_arg
    type          longword (unsigned)
    access        read only
    mechanism     by value
    Optional user-defined value to be signaled when the event occurs.
    The signal-value argument is an unsigned longword containing this
    value.

4.25  –  PPL$FIND_OBJECT_ID

    Given the name of a spin lock, semaphore, barrier, event, work
    queue, or shared memory zone, the Find Object Identification
    routine returns the identifier of the object associated with the
    name you specify.

    Format

      PPL$FIND_OBJECT_ID  object-id ,object-name

4.25.1  –  Arguments

 object-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        modify
    mechanism     by reference
    Object identifier to be returned. The object-id argument is the
    address of an unsigned longword that receives the associated
    identifier.

 object-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the object for which to return the associated identifier.
    The object-name argument is the address of a descriptor pointing
    to a character string containing the (user-defined) name of the
    object.

4.26  –  PPL$FLUSH_SHARED_MEMORY

    The Flush Shared Memory routine writes (flushes) to disk
    the contents of a global section that you created using the
    PPL$CREATE_SHARED_MEMORY routine. Only pages that have been
    modified are flushed to disk.

    Format

      PPL$FLUSH_SHARED_MEMORY  section-name [,memory-area] [,flags]

4.26.1  –  Arguments

 section-name

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    Name of the global section whose contents are to be written to
    disk. The section-name argument is the address of a descriptor
    pointing to a character string containing the global section
    name.

 memory-area

    OpenVMS usage vector_longword_unsigned
    type          longword (unsigned)
    access        read only
    mechanism     by reference, array reference
    The area of memory into which the specified global section
    is mapped. The memory-area argument is the address of a two-
    longword array containing, in order, the length (in bytes) and
    the starting virtual address for the area of memory.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Bit mask specifying actions to perform before flushing the global
    section. The flags argument is the address of a longword bit mask
    containing the flag. The valid value for flags is as follows:

    PPL$M_NOUNI   Identifies the global section as having a nonunique
                  name. By default, PPL$CREATE_SHARED_MEMORY gives
                  the specified global section a name unique to
                  the application by using PPL$UNIQUE_NAME. If you
                  specified this value to give the global section a
                  nonunique name when you called PPL$CREATE_SHARED_
                  MEMORY, you must also specify it when you call
                  PPL$FLUSH_SHARED_MEMORY.

4.27  –  PPL$GET_INDEX

    The Get Index of a Participant routine returns an index that
    is unique within the application. A value of zero signifies the
    participant that formed the application. The other participants
    in the application always return an index greater than zero.

    Format

      PPL$GET_INDEX  participant-index

4.27.1  –  Arguments

 participant-index

    OpenVMS usage longword_unsigned
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    The index of the caller within this application. The participant-
    index argument is the address of an unsigned longword that
    contains this index. This index is assigned at process creation
    time and is unique for each participant.

4.28  –  PPL$INCREMENT_SEMAPHORE

    The Increment a Semaphore routine increments the value of the
    semaphore by 1, analogous to the signal protocol. If any other
    participants are blocked on a call to PPL$DECREMENT_SEMAPHORE for
    this semaphore, one is removed from the queue and awakened. The
    semaphore must have been created by PPL$CREATE_SEMAPHORE.

    Format

      PPL$INCREMENT_SEMAPHORE  semaphore-id

4.28.1  –  Arguments

 semaphore-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the semaphore. The semaphore-id argument is the
    address of an unsigned longword containing the identifier.

    Semaphore-id is returned by PPL$CREATE_SEMAPHORE.

4.29  –  PPL$INDEX_TO_PID

    The Convert Participant Index to OpenVMS PID routine returns the
    OpenVMS PID of the process associated with the specified index.

    Format

      PPL$INDEX_TO_PID  participant-index ,pid

4.29.1  –  Arguments

 participant-index

    OpenVMS usage longword_unsigned
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Index of the caller within this application. The participant-
    index argument is the address of an unsigned longword that
    contains this index. Participant-index is assigned at process
    creation time and is unique for each participant.

 pid

    OpenVMS usage longword_unsigned
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    PID (process identifier) of the OpenVMS process associated with
    the specified participant-index. The pid argument is the address
    of an unsigned longword that receives this PID.

4.30  –  PPL$INSERT_WORK_ITEM

    The Insert a Work Queue Item routine inserts a work item into the
    specified work queue.

    Format

      PPL$INSERT_WORK_ITEM  queue-id ,work-item [,flags] [,priority]

4.30.1  –  Arguments

 queue-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    The queue identifier. The queue-id argument is the address of an
    unsigned longword containing the identifier.

 work-item

    OpenVMS usage user_arg
    type          longword (unsigned)
    access        read only
    mechanism     by value
    A value to be entered into the queue. The work-item argument
    is an unsigned longword containing this value. The content of
    work-item is completely arbitrary. You may want to place single
    longword values into work-item (for example, the number of a
    function or task to be performed). You can also use work-item to
    pass a pointer to a data block. (This data block must reside in
    memory created by PPL$CREATE_SHARED_MEMORY or allocated from a
    shared memory zone created by PPL$CREATE_VM_ZONE.)

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Specifies options for inserting a work item into a work queue.
    The optional flags argument is the address of a longword bit mask
    containing the flag. The valid value is as follows:

    PPL$M_ATHEAD  Insert item as the first of those items with the
                  same priority (in other words, at the head of the
                  priority). By default, items are inserted after
                  other items of the same priority.

 priority

    OpenVMS usage longword_signed
    type          longword (signed)
    access        read only
    mechanism     by reference
    Specifies the priority of the item being inserted. The optional
    priority argument is an unsigned longword containing the priority
    value for the item to be inserted. If unspecified, the default
    value is zero. A high numerical value indicates a high priority.

4.31  –  PPL$PID_TO_INDEX

    The Convert OpenVMS PID to Participant Index routine returns the
    PPL$-defined participant index of the process associated with the
    specified OpenVMS PID.

    Format

      PPL$PID_TO_INDEX  pid ,participant-index

4.31.1  –  Arguments

 pid

    OpenVMS usage longword_unsigned
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    PID (process identifier) of the OpenVMS process or subprocess
    whose participant index is to be obtained. The pid argument is
    the address of an unsigned longword that contains this PID.

 participant-index

    OpenVMS usage longword_unsigned
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Participant index of the process or subprocess associated with
    the specified OpenVMS PID. The participant-index argument is
    the address of an unsigned longword that receives this index.
    Participant-index is assigned by the PPL$ facility at process
    creation time and is unique for each participant.

4.32  –  PPL$READ_BARRIER

    The Read a Barrier routine returns the specified barrier's
    current quorum and the number of participants currently waiting
    (blocked) at the barrier. The barrier must have been created by
    PPL$CREATE_BARRIER.

    Format

      PPL$READ_BARRIER  barrier-id ,quorum ,waiters

4.32.1  –  Arguments

 barrier-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the specified event. The barrier-id argument is the
    address of an unsigned longword containing the identifier.

    Barrier-id is returned by PPL$CREATE_BARRIER.

 quorum

    OpenVMS usage word_signed
    type          word (signed)
    access        write only
    mechanism     by reference
    Number of participants required to terminate a wait for this
    barrier. The quorum argument is the address of a signed word
    containing the quorum value. This argument returns the current
    quorum value that you set with PPL$CREATE_BARRIER, PPL$SET_
    QUORUM, or PPL$ADJUST_QUORUM.

 waiters

    OpenVMS usage word_signed
    type          word (signed)
    access        write only
    mechanism     by reference
    Number of participants currently waiting at this barrier. The
    waiters argument is the address of a signed word containing the
    number of waiting participants.

4.33  –  PPL$READ_EVENT

    The Read an Event State routine returns the current state of the
    specified event. The state can be occurred or not_occurred.

    Format

      PPL$READ_EVENT  event-id ,occurred

4.33.1  –  Arguments

 event-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the specified event. The event-id argument is the
    address of an unsigned longword containing the identifier.

    Event-id is returned by PPL$CREATE_EVENT.

 occurred

    OpenVMS usage longword_unsigned
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Receives the state of the specified event. The occurred argument
    is the address of an unsigned longword that receives the event
    state. This argument returns a value of true if the current state
    of the event is occurred, and returns false if the current state
    of the event is not_occurred.

4.34  –  PPL$READ_SEMAPHORE

    The Read Semaphore Values routine returns the current or maximum
    values, or both, of the specified counting semaphore. The
    semaphore must have been created by PPL$CREATE_SEMAPHORE.

    Format

      PPL$READ_SEMAPHORE  semaphore-id [,semaphore-value]

                          [,semaphore-maximum]

4.34.1  –  Arguments

 semaphore-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the specified semaphore. The semaphore-id argument
    is the address of an unsigned longword containing the identifier.

    Semaphore-id is returned by PPL$CREATE_SEMAPHORE.

 semaphore-value

    OpenVMS usage word_signed
    type          word (signed)
    access        write only
    mechanism     by reference
    Receives information about the specified semaphore. The optional
    semaphore-value argument is the address of a signed word
    containing the current value of the semaphore or the number of
    blocked processes. If positive, semaphore-value contains the
    number of available resources associated with this semaphore;
    if negative, it contains the number of waiting processes. If the
    value returned is zero, there are no available resources and no
    waiting processes.

 semaphore-maximum

    OpenVMS usage word_signed
    type          word (signed)
    access        write only
    mechanism     by reference
    Maximum value of the semaphore. The semaphore-maximum argument is
    the address of a signed word containing the maximum value of the
    semaphore specified by semaphore-id.

4.35  –  PPL$READ_SPIN_LOCK

    The Read a Spin Lock State routine returns the current state of a
    spin lock. The state can be seized or not_seized.

    Format

      PPL$READ_SPIN_LOCK  lock-id ,seized

4.35.1  –  Arguments

 lock-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the specified spin lock. The lock-id argument is
    the address of an unsigned longword containing the identifier.

 seized

    OpenVMS usage longword_unsigned
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Receives the state of the specified spin lock. The seized
    argument is the address of an unsigned longword that receives
    the spin lock state. This argument returns a value of true if the
    current state of the spin lock is seized, and it returns a value
    of false if the current state of the spin lock is not_seized.

4.36  –  PPL$READ_WORK_QUEUE

    The Read a Work Queue routine returns information about a work
    queue.

    Format

      PPL$READ_WORK_QUEUE  queue-id [,queue-value]

4.36.1  –  Arguments

 queue-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    The queue identifier. The queue-id argument is the address of an
    unsigned longword containing the identifier.

 queue-value

    OpenVMS usage longword_signed
    type          longword (signed)
    access        write only
    mechanism     by reference
    Receives information about the specified work queue. If positive,
    queue-value contains the number of items currently in the work
    queue; if negative, it contains the number of processes currently
    blocked (waiting for an item to be placed in the queue). If the
    value returned is zero, there are no work items in the queue and
    no blocked processes. The optional queue-value argument is the
    address of a signed longword that receives the number of work
    items or blocked processes.

4.37  –  PPL$RELEASE_SPIN_LOCK

    The Release Spin Lock routine relinquishes the spin lock by
    clearing the bit representing the lock. The lock must have been
    created by PPL$CREATE_SPIN_LOCK.

    Format

      PPL$RELEASE_SPIN_LOCK  lock-id

4.37.1  –  Arguments

 lock-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the specified lock. The lock-id argument is the
    address of an unsigned longword containing the lock identifier.

    Lock-id is returned by PPL$CREATE_SPIN_LOCK.

4.38  –  PPL$REMOVE_WORK_ITEM

    The Remove a Work Queue Item routine removes the next item in
    order from a work queue.

    Format

      PPL$REMOVE_WORK_ITEM  queue-id ,work-item [,flags] [,spin]

4.38.1  –  Arguments

 queue-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    The queue identifier. The queue-id argument is the address of an
    unsigned longword containing the identifier.

 work-item

    OpenVMS usage user_arg
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Receives the value of the item that is removed from the work
    queue. The work-item argument is the address of an unsigned
    longword that receives the value of the item that is removed
    from the work queue.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Specifies options for removing an item from the work queue. The
    optional flags argument is the address of a longword bit mask
    containing the flag. Valid values are as follows:

    PPL$M_NON_         If the specified work queue is empty, return
    BLOCKING           immediately with the PPL$_NOT_AVAILABLE status
                       indicating that no items are available to be
                       removed from the work queue. By default, if
                       the work queue is empty the process hibernates
                       until there is an item available to be removed
                       from the work queue.
    PPL$M_FROMTAIL     Remove item from the end (or tail) of the work
                       queue. By default, this routine removes an
                       item from the beginning (or head) of the work
                       queue.
    PPL$M_SPIN_WAIT    Indicates that the caller is never to block,
                       but rather to always spin while waiting at
                       this barrier.
    PPL$M_SPIN_        Indicates that the caller wishes to spin for
    COUNTED            a given amount of instructions and then to
                       block. The default is block immediately, do
                       not spin at all.

 spin

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    This value must be specified when using the PPL$M_SPIN_COUNTED
    flag and represents a relative time that a process will spin
    before blocking.

4.39  –  PPL$RESET_EVENT

    The Reset an Event routine resets an event's state to not_
    occurred.

    Format

      PPL$RESET_EVENT  event-id

4.39.1  –  Arguments

 event-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the event. The event-id argument is the address of
    an unsigned longword containing the identifier.

4.40  –  PPL$SEIZE_SPIN_LOCK

    The Seize Spin Lock routine retrieves a simple (spin) lock by
    waiting in a spin loop until the lock is free. The lock must have
    been created by PPL$CREATE_SPIN_LOCK.

    Format

      PPL$SEIZE_SPIN_LOCK  lock-id [,flags]

4.40.1  –  Arguments

 lock-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the lock to be seized. The lock-id argument is the
    address of an unsigned longword containing the lock identifier.

    Lock-id is returned by PPL$CREATE_SPIN_LOCK.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Bit mask specifying options for seizing the lock. The flags
    argument is a longword bit mask containing the flag. The valid
    value for flags is as follows:

    PPL$M_NON_         The lock is seized if and only if it can
    BLOCKING           be done without causing the caller to wait
                       (spin). (This can be useful in situations
                       where the cost of waiting for a resource is
                       not desirable, or if the caller merely intends
                       to request immediate access to any one of a
                       number of resources.)

4.41  –  PPL$SET_QUORUM

    The Set Barrier Quorum routine dynamically sets a value for the
    specified barrier's quorum.

    Format

      PPL$SET_QUORUM  barrier-id ,quorum

4.41.1  –  Arguments

 barrier-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the barrier. The barrier-id argument is the address
    of the barrier identifier.

    Barrier-id is returned by PPL$CREATE_BARRIER.

 quorum

    OpenVMS usage word_signed
    type          word (signed)
    access        read only
    mechanism     by reference
    The number of participants required to terminate an active
    wait for this barrier. The quorum argument is the address of a
    signed word containing the quorum number. For example, a quorum
    value of 3 indicates that the first two callers of PPL$WAIT_
    AT_BARRIER specifying this barrier-id are blocked until a third
    participant calls PPL$WAIT_AT_BARRIER. At that point, all three
    are released for further processing. If you specify zero for
    quorum, the quorum is set to the number of processes currently in
    the application. The value of quorum must be positive or zero.

4.42  –  PPL$SET_SEMAPHORE_MAXIMUM

    The Set a Semaphore Maximum routine dynamically sets the maximum
    value of a semaphore.

    Format

      PPL$SET_SEMAPHORE_MAXIMUM  semaphore-id ,semaphore-maximum

4.42.1  –  Arguments

 semaphore-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the semaphore. The semaphore-id argument is the
    address of an unsigned longword containing the identifier.

 semaphore-maximum

    OpenVMS usage word_signed
    type          word (signed)
    access        read only
    mechanism     by reference
    New maximum value of the semaphore. The semaphore-maximum
    argument is the address of a signed word containing the maximum
    value. This value must be nonnegative.

4.43  –  PPL$SPAWN

    The Initiate Parallel Execution routine executes code in parallel
    with the caller by creating one or more subordinate threads of
    execution (OpenVMS subprocesses).

    Format

      PPL$SPAWN  copies [,program-name] [,children-ids] [,flags]

                 [,std-input-file] [,std-output-file]

4.43.1  –  Arguments

 copies

    OpenVMS usage longword_unsigned
    type          longword (unsigned)
    access        modify
    mechanism     by reference
    Number of subordinates of the specified program to be executed
    concurrently. The copies argument is the address of an unsigned
    longword containing this number. Its value must be positive.
    If you specify a value greater than 1 for the copies argument,
    each copy created will have the same subprocess information (for
    example, standard input and output files). If you want to specify
    different information for each subprocess, call PPL$SPAWN once
    for each subprocess.

    On output, this parameter contains the number of subordinates
    actually created. This value differs from the requested number
    if an individual spawn attempt fails, for example, because of
    insufficient quotas.

 program-name

    OpenVMS usage logical_name
    type          character string
    access        read only
    mechanism     by descriptor, fixed-length
    Name of the program (image) to be invoked. The program-name
    argument is the address of a descriptor pointing to a character
    string containing the file specification of the image. Program-
    name must have no more than 63 characters. If program-name
    contains a logical name, the equivalence name must be in a
    logical name table that the created subordinate can access. If
    you do not specify a program-name, the default is to execute in
    parallel the image being run by the caller.

 children-ids

    OpenVMS usage vector_longword_unsigned
    type          longword (unsigned)
    access        write only
    mechanism     by reference, array reference
    Identifiers of each of the newly created subordinates. The
    children-ids argument is the address of a vector of longwords
    into which is written the index within the executing application
    of each subordinate successfully initiated by this call.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Bit mask specifying options for creating processes. The flags
    argument is a longword bit mask containing the flags. Valid
    values for flags are as follows:

    PPL$M_INIT_      If set, the caller of this routine and
    SYNCH            all subordinates created by this call are
                     synchronized to continue processing only after
                     each and every subordinate created by this call
                     has called PPL$CREATE_APPLICATION. (See the
                     Description section for more information.) A
                     failure of the created subordinate after it
                     successfully starts but before its call to
                     PPL$CREATE_APPLICATION can cause difficulties
                     with the use of this flag value.
    PPL$M_NOCLISYM   If set, the created processes do not inherit CLI
                     symbols from the calling process. The default
                     action is for created processes to inherit all
                     currently defined CLI symbols.
    PPL$M_           If set, prompt strings are not prefixed by
    NOCONTROL        carriage return/line feeds. The default action
                     is to prefix any prompt string specified with a
                     carriage return/line feed.
    PPL$M_NODEBUG    Prevents the startup of the OpenVMS Debugger,
                     even if the debugger was linked with the image.
    PPL$M_NOKEYPAD   If set, created processes inherit the current
                     keypad symbols and state from the calling
                     process. The default action is that created
                     processes do not inherit keypad symbols and
                     state.
    PPL$M_NOLOGNAM   If set, created processes do not inherit process
                     logical names from the calling process. The
                     default is for created processes to inherit all
                     currently defined process logical names.
    PPL$M_NOTIFY     If set, a message is broadcast to SYS$OUTPUT as
                     each process terminates. This flag is ignored if
                     the process is not interactive (for example, run
                     in batch).

 std-input-file

    OpenVMS usage logical-name
    type          character string
    access        read only
    mechanism     by descriptor
    File name of the file to serve as the standard input file in the
    created subordinates. The std-input-file argument is the address
    of a descriptor pointing to a character string containing the
    file name. If you do not specify a value for this argument, the
    subordinate inherits the creating participant's standard input
    file (SYS$INPUT).

 std-output-file

    OpenVMS usage logical-name
    type          character string
    access        read only
    mechanism     by descriptor
    File name of the file to serve as the standard output file in the
    created subordinates. The std-output-file argument is the address
    of a descriptor pointing to a character string containing the
    file name. If you do not specify a value for this argument, the
    subordinate inherits the creating participant's standard output
    file (SYS$OUTPUT).

4.44  –  PPL$STOP

    The Stop a Participant routine terminates the execution of the
    specified participant in this application.

    Format

      PPL$STOP  participant-index

4.44.1  –  Arguments

 participant-index

    OpenVMS usage longword_unsigned
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    PPL$-defined index of the participant to be terminated. The
    participant-index argument is the address of an unsigned longword
    containing the index.

    Participant-index is obtained by a call to PPL$SPAWN or PPL$GET_
    INDEX.

4.45  –  PPL$TERMINATE

    The Abort PPL$ Participation routine ends the caller's
    participation in the application "prematurely"-that is, at some
    time before the caller actually completes its execution.

    Format

      PPL$TERMINATE  [flags]

4.45.1  –  Arguments

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Bit mask specifying options for terminating access to PPL$. The
    flags argument is the address of a longword bit mask containing
    the flag. The flags argument accepts the following value:

    PPL$M_STOP_        Terminates all subordinates created by
    CHILDREN           the caller in addition to terminating the
                       caller itself. (PPL$ makes no effort to
                       delete subordinates at process termination
                       in the absence of a call to this routine
                       specifying this flag value, but note that an
                       OpenVMS subprocess is deleted when the parent
                       terminates.)

4.46  –  PPL$TRIGGER_EVENT

    The Trigger an Event routine causes the event's state to become
    occurred. You control whether all pending actions for the event
    are processed (made to occur), or just one is processed. A
    pending action can be an AST, a signal (condition), or a wakeup.

    Format

      PPL$TRIGGER_EVENT  event-id [,event-param] [,flags]

4.46.1  –  Arguments

 event-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the event. The event-id argument is the address of
    an unsigned longword containing the identifier.

    Event-id is returned by PPL$CREATE_EVENT.

 event-param

    OpenVMS usage user_arg
    type          longword (unsigned)
    access        read only
    mechanism     by value
    An arbitrary value to be passed to all requests processed for
    the event as a result of the trigger, or, if there are no queued
    event notification requests for this event, to the first caller
    to enable event notification. The event-param argument is the
    address of an unsigned longword containing this value. The value
    of event-param is received by the output argument of PPL$AWAIT_
    EVENT.

    If a participant enables delivery of an AST by calling
    PPL$ENABLE_EVENT_AST, this argument appears in the second
    longword of the vector specified by the astprm argument. If a
    participant enables delivery of a signal by calling PPL$ENABLE_
    EVENT_SIGNAL, this argument appears as the third longword in the
    signal vector when the condition is raised.

 flags

    OpenVMS usage mask_longword
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Specifies options for triggering an event. The flags argument is
    the address of a longword bit mask containing the flag. The valid
    value for flags is as follows:

    PPL$M_NOTIFY_ONE   Processes exactly one enabled event
                       notification. By default, all pending actions
                       are processed when the event state becomes
                       occurred.

4.47  –  PPL$UNIQUE_NAME

    The Produce a Unique Name routine returns an application-unique
    name. A system-unique string specific to the calling application
    is appended to the string specified by the user. The resulting
    name is identical for all participants in the application, but
    different from those for all other applications on that system.

    Format

      PPL$UNIQUE_NAME  name-string ,resultant-string

                       [,resultant-length] [,flags]

4.47.1  –  Arguments

 name-string

    OpenVMS usage char_string
    type          character string
    access        read only
    mechanism     by descriptor
    The user-supplied string to be appended by the 'TOP' processes'
    PID. When combined, they will provide a name unique to this
    application.

 resultant-string

    OpenVMS usage char_string
    type          character string
    access        write only
    mechanism     by descriptor
    Resulting unique name. The resultant-string argument is the
    address of a descriptor pointing to a character string containing
    this name. Resultant-string consists of the name-string string
    and an appended system-unique string.

 resultant-length

    OpenVMS usage word_unsigned
    type          word (unsigned)
    access        write only
    mechanism     by reference
    Length of the unique name returned as the resultant-string. The
    resultant-length argument is the address of an unsigned word
    containing this length.

 flags

    OpenVMS usage word_unsigned
    type          longword (unsigned)
    access        write only
    mechanism     by reference
    Specifies whether the supplied name should be unique to the
    application, to the calling process, or to this particular call.
    The default is application-unique. The valid values for flags are
    as follows:

    PPL$M_PROC_UNIQUE  Indicates that the caller wishes the returned
                       name to be unique to the calling process.
    PPL$M_CALL_UNIQUE  Indicates that the caller wishes the returned
                       name to be unique to this particular call.

4.48  –  PPL$WAIT_AT_BARRIER

    The Synchronize at a Barrier routine causes the caller to wait at
    the specified barrier. The barrier is in effect from the time the
    first participant calls PPL$WAIT_AT_BARRIER until each member of
    the quorum has issued the call. At that time, the wait concludes
    and all are released for further execution.

    Format

      PPL$WAIT_AT_BARRIER  barrier-id ,flags ,spin

4.48.1  –  Arguments

 barrier-id

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Identifier of the barrier. The barrier-id argument is the address
    of an unsigned longword containing the barrier identifier.

    Barrier-id is returned by PPL$CREATE_BARRIER.

 flags

    OpenVMS usage identifier
    type          longword (unsigned)
    access        read only
    mechanism     by reference
    Specifies options for the wait_at_barrier operation. The flags
    argument is the value of a longword bit mask containing the flag.
    The bit, when set, specifies the corresponding option. Valid
    values for flags are as follows:

    PPL$M_SPIN_WAIT    Indicates that the caller is never to block,
                       but rather to always spin while waiting at
                       this barrier.
    PPL$M_SPIN_        Indicates that the caller wishes to spin for
    COUNTED            a given amount of instructions and then to
                       block.

    The default is block immediately, do not spin at all.

 spin

    OpenVMS usage identifier
    type          long (unsigned)
    access        read only
    mechanism     by reference
    This value must be specified when using the PPL$M_SPIN_COUNTED
    flag and represents a relative time that a process will spin
    before blocking.

5  –  SMG$

5.1  –  SMG$ADD_KEY_DEF

    The Add Key Definition routine adds a keypad key definition to a
    table of key definitions.

    Format

      SMG$ADD_KEY_DEF  key-table-id ,key-name [,if-state]

                       [,attributes] [,equivalence-string]

                       [,state-string]

5.1.1  –  Returns

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

5.1.2  –  Arguments

 key-table-id

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

    Identifies the key table to which you are adding a key
    definition. The key-table-id argument is the address of an
    unsigned longword that contains the key table identifier.

    The key table identifier argument is returned by the SMG$CREATE_
    KEY_TABLE routine.

 key-name

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

    Identifies the key whose value you are defining. The key-name
    argument is the address of a descriptor pointing to this key
    name. The SMG$ADD_KEY_DEF routine changes the string to uppercase
    and removes trailing blanks.

 if-state

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

    Qualifies the value returned when key-name is pressed. The if-
    state argument is the address of a descriptor pointing to the
    state string.

    If if-state is specified, this definition of key-name is used
    only if the current state matches the specified if-state string.
    The if-state argument must be from 1 to 31 characters in length.
    If this argument is omitted, if-state defaults to the value
    DEFAULT.

 attributes

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

    Longword bit mask specifying additional attributes of this key
    definition. The attributes argument is the address of an unsigned
    longword that contains this attribute mask. If omitted, the mask
    is zero.

    Valid attributes are described in the following list:

    SMG$M_KEY_NOECHO       If set, this bit specifies that
                           equivalence-string is not to be echoed
                           when this key is pressed. If clear,
                           equivalence-string is echoed. If SMG$M_
                           KEY_TERMINATE is not set, SMG$M_KEY_NOECHO
                           is ignored.
    SMG$M_KEY_TERMINATE    If set, this bit specifies that when
                           this key is pressed (as qualified by if-
                           state) the input line is complete and
                           more characters should not be accepted.
                           If clear, more characters may be accepted.
                           In other words, setting this bit causes
                           equivalence-string to be treated as a
                           terminator.
    SMG$M_KEY_LOCK         If set, and if state-string is specified,
                           the state name specified by state-string
                           remains the current state until explicitly
                           changed by a subsequent keystroke whose
                           definition includes a state-string. If
                           clear, the state name specified by state-
                           string remains in effect only for the next
                           defined keystroke.
    SMG$M_KEY_PROTECTED    If set, this bit specifies that this
                           key definition cannot be modified or
                           deleted. If clear, the key definition can
                           be modified or deleted.

    The remaining bits are undefined and must be zero. It is possible
    to perform a logical OR operation on these values to set more
    than one attribute at a time.

 equivalence-string

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

    Character string to be substituted for the keystroke in the
    returned line. The equivalence-string argument is the address
    of a descriptor pointing to this equivalence string.

    The equivalence-string argument is displayed unless SMG$M_KEY_
    NOECHO is set. If equivalence-string is omitted, no equivalence
    string is defined for this key.

 state-string

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

    Contains a new state name that becomes the current state when
    this key is pressed. The state-string argument is the address of
    a descriptor pointing to the new state string.

    If omitted, no new state is defined. If the current state is
    temporary (that is, if SMG$M_KEY_LOCKSTATE was not specified for
    the most recently pressed defined key), the current state-string
    becomes DEFAULT.

5.2  –  SMG$BEGIN_DISPLAY_UPDATE

    The Begin Batching of Display Updates routine saves, or batches,
    all output to a virtual display until a matching call to SMG$END_
    DISPLAY_UPDATE is encountered.

    Format

      SMG$BEGIN_DISPLAY_UPDATE  display-id

5.2.1  –  Returns

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

5.2.2  –  Argument

 display-id

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

    Specifies the virtual display for which output is to be batched.
    The display-id argument is the address of an unsigned longword
    that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

5.3  –  SMG$BEGIN_PASTEBOARD_UPDATE

    The Begin Batching of Pasteboard Updates routine saves, or
    batches, all output to a pasteboard until a matching call to
    SMG$END_PASTEBOARD_UPDATE is encountered.

    Format

      SMG$BEGIN_PASTEBOARD_UPDATE  pasteboard-id

5.3.1  –  Returns

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

5.3.2  –  Argument

 pasteboard-id

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

    Specifies the pasteboard for which output is to be batched. The
    pasteboard-id argument is the address of an unsigned longword
    that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

5.4  –  SMG$CANCEL_INPUT

    The Cancel Input Request routine immediately cancels any read-
    in-progress that was issued by SMG$READ_COMPOSED_LINE, SMG$READ_
    KEYSTROKE, SMG$READ_STRING, or SMG$READ_VERIFY.

    Format

      SMG$CANCEL_INPUT  keyboard-id

5.4.1  –  Returns

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

5.4.2  –  Argument

 keyboard-id

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

    Specifies the virtual keyboard for which the input is to be
    canceled. The keyboard-id argument is the address of an unsigned
    longword that contains the keyboard identifier.

    The keyboard identifier is returned by SMG$CREATE_VIRTUAL_
    KEYBOARD.

5.5  –  SMG$CHANGE_PBD_CHARACTERISTICS

    The Change Pasteboard Characteristics routine lets you change the
    characteristics associated with a pasteboard.

    Format

      SMG$CHANGE_PBD_CHARACTERISTICS  pasteboard-id

                                      [,desired-width] [,width]

                                      [,desired-height] [,height]

                                      [,desired-background-color]

                                      [,background-color]

5.5.1  –  Returns

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

5.5.2  –  Arguments

 pasteboard-id

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

    Specifies the pasteboard whose characteristics are to be changed.
    The pasteboard-id argument is the address of an unsigned longword
    that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 desired-width

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

    New width for the pasteboard. The desired-width argument is the
    address of a signed longword that contains the desired width. If
    omitted, the width does not change.

 width

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

    Receives the physical width of the pasteboard. The width argument
    is the address of a signed longword into which is written the
    actual width of the pasteboard.

    If the terminal cannot be set exactly to desired-width, width
    may be larger than desired-width. If the physical width of the
    terminal is smaller than desired-width, width may be smaller than
    desired-width.

 desired-height

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

    New height for the pasteboard. The desired-height argument is the
    address of a signed longword that contains the desired height of
    the pasteboard. If desired-height is omitted, the height does not
    change.

 height

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

    Receives the physical height of the pasteboard. The height
    argument is the address of a signed longword into which is
    written the actual height of the pasteboard.

    If the terminal cannot be set exactly to desired-height, height
    may be larger than desired-height. If the physical height of the
    terminal is smaller than desired-height, height may be smaller
    than desired-height.

 desired-background-color

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

    Symbolic name for the desired background color. The desired-
    background-color argument is the address of an unsigned longword
    that contains the desired color.

    The symbols listed below are defined in $SMGDEF. Valid values for
    desired-background-color are as follows:

    SMG$C_COLOR_WHITE    Light background
    SMG$C_COLOR_BLACK    Dark background
    SMG$C_COLOR_BLUE     Blue background
    SMG$C_COLOR_CYAN     Cyan (green-blue) background
    SMG$C_COLOR_GREEN    Green background
    SMG$C_COLOR_         Magenta background
    MAGENTA
    SMG$C_COLOR_RED      Red background
    SMG$C_COLOR_YELLOW   Yellow background
    SMG$C_COLOR_LIGHT    White background
    SMG$C_COLOR_DARK     Black background
    SMG$C_COLOR_USER1    User-defined background 1
    SMG$C_COLOR_USER2    User-defined background 2
    SMG$C_COLOR_USER3    User-defined background 3
    SMG$C_COLOR_USER4    User-defined background 4
    SMG$C_COLOR_USER5    User-defined background 5
    SMG$C_COLOR_USER6    User-defined background 6
    SMG$C_COLOR_USER7    User-defined background 7
    SMG$C_COLOR_USER8    User-defined background 8

    If you omit desired-background-color, or if the terminal hardware
    does not support the background color specified, the background
    color is not changed.

 background-color

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

    Receives the background color chosen. The background-color
    argument is the address of an unsigned longword into which is
    written the background color.

    This routine may return any of the values listed in the desired-
    background-color argument description or SMG$C_COLOR_UNKNOWN. If
    the desired-background-color argument is omitted, the value of
    background-color does not change.

5.6  –  SMG$CHANGE_RENDITION

    The Change Default Rendition routine changes the video attributes
    for all or part of a virtual display.

    Format

      SMG$CHANGE_RENDITION  display-id ,start-row ,start-column

                            ,number-of-rows ,number-of-columns

                            [,rendition-set] [,rendition-complement]

5.6.1  –  Returns

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

5.6.2  –  Arguments

 display-id

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

    Specifies the virtual display whose default rendition is to be
    changed. The display-id argument is the address of an unsigned
    longword that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

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

    Starting row position to receive the new rendition. The start-row
    argument is the address of a signed longword that contains the
    starting row number.

 start-column

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

    Starting column position to receive the new rendition. The start-
    column argument is the address of a signed longword that contains
    the starting column number.

 number-of-rows

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

    Number of rows to receive the new rendition. The number-of-rows
    argument is the address of a signed longword that contains the
    number of rows to be affected.

 number-of-columns

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

    Number of columns to receive the new rendition. The number-
    of-columns argument is the address of a signed longword that
    contains the number of columns to be affected.

 rendition-set

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

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

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

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to
    be complemented in the display. All of the attributes that can
    be specified with the rendition-set argument can be complemented
    with the rendition-complement argument. The display-id argument
    must be specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

5.7  –  SMG$CHANGE_VIEWPORT

    The Change the Viewport Associated with a Virtual Display routine
    changes the size of an existing viewport in a virtual display.
    The text currently in the viewport is remapped to fit the new
    dimensions.

    Format

      SMG$CHANGE_VIEWPORT  display-id [,viewport-row-start]

                           [,viewport-column-start]

                           [,viewport-number-rows]

                           [,viewport-number-columns]

5.7.1  –  Returns

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

5.7.2  –  Arguments

 display-id

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

    Identifier of the virtual display containing the viewport to be
    changed. The display-id argument is the address of an unsigned
    longword containing this identifier.

 viewport-row-start

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

    Optional row number in the virtual display that will become row
    1 in the changed viewport. The viewport-row-start argument is
    the address of a signed longword containing the row number. If
    omitted, the present viewport-row-start value is used.

 viewport-column-start

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

    Optional column number in the virtual display that will become
    column 1 in the changed viewport. The viewport-column-start
    argument is the address of a signed longword containing the
    column number. If omitted, the present viewport-column-start
    value is used.

 viewport-number-rows

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

    Optional number of rows in the changed viewport. The viewport-
    number-rows argument is the address of a signed longword
    containing the number of rows. If omitted, the present viewport-
    number-rows value is used.

 viewport-number-columns

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

    Optional number of columns in the changed viewport. The viewport-
    number-columns argument is the address of a signed longword
    containing the number of columns. If omitted, the present
    viewport-number-columns value is used.

5.8  –  SMG$CHANGE_VIRTUAL_DISPLAY

    The Change Virtual Display routine lets you change the
    dimensions, border, and video attributes of a virtual display.

    Format

      SMG$CHANGE_VIRTUAL_DISPLAY  display-id [,number-of-rows]

                                  [,number-of-columns]

                                  [,display-attributes]

                                  [,video-attributes]

                                  [,character-set]

5.8.1  –  Returns

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

5.8.2  –  Arguments

 display-id

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

    Specifies the virtual display whose attributes are to be changed.
    The display-id argument is the address of an unsigned longword
    that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 number-of-rows

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

    Specifies the new number of rows for the virtual display. The
    number-of-rows argument is the address of a signed longword that
    contains the number of rows in the virtual display.

 number-of-columns

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

    Specifies the new number of columns for the virtual display. The
    number-of-columns argument is the address of a signed longword
    that contains the number of columns in the virtual display.

 display-attributes

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

    Specifies the attributes of the virtual display. The display-
    attributes argument is the address of a longword bit mask that
    contains the display attributes.

    Valid values for display-attributes are as follows:

    SMG$M_BORDER       Specifies a bordered display. If omitted, the
                       display is not bordered.
    SMG$M_BLOCK_       Specifies a block bordered display. If
    BORDER             omitted, the display is not bordered.
    SMG$M_DISPLAY_     Specifies that control characters such as
    CONTROLS           carriage return and line feed are displayed as
                       graphic characters, if your terminal supports
                       them.
    SMG$M_TRUNC_ICON   Specifies that an icon (generally a diamond
                       shape) is displayed where truncation of a line
                       exceeding the width of the virtual display has
                       occurred.

 video-attributes

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

    Specifies the default rendition to be applied to all output in
    a virtual display, unless overridden by a call to a specific
    output routine. The video-attributes argument is the address of
    an unsigned longword that contains the video attributes mask.

    For example, a call to SMG$PUT_CHARS with an explicit rendition
    specified would override the default rendition.

    The bits that can be set for this argument are as follows:

    SMG$M_BLINK        Displays blinking characters.
    SMG$M_BOLD         Displays characters in higher-than-normal
                       intensity.
    SMG$M_REVERSE      Displays characters in reverse video; that
                       is, to the opposite of the current default
                       rendition of the virtual display.
    SMG$M_UNDERLINE    Displays underlined characters.
    SMG$M_INVISIBLE    Specifies invisible characters; that is, the
                       characters exist in the virtual display but do
                       not appear on the pasteboard.
    SMG$M_USER1        Displays user-defined attributes.
    through
    SMG$M_USER8

    You can specify any combination of attributes in a single call.
    All other bits are reserved for use by VSI and must be 0.

 character-set

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

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set specifier. Valid values
    are SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.

5.9  –  SMG$CHECK_FOR_OCCLUSION

    The Check for Occlusion routine checks to see whether a virtual
    display is covered (occluded) by another virtual display.

    Format

      SMG$CHECK_FOR_OCCLUSION  display-id ,pasteboard-id

                               ,occlusion-state

5.9.1  –  Returns

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

5.9.2  –  Arguments

 display-id

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

    Specifies the virtual display to be checked. The display-id
    argument is the address of an unsigned longword that contains
    the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 pasteboard-id

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

    Specifies the pasteboard to be checked. The pasteboard-id
    argument is the address of an unsigned longword that contains
    the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 occlusion-state

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

    Receives the value denoting whether the display is occluded. The
    occlusion-state argument is the address of a signed longword into
    which the occlusion state is written. Occlusion-state is set to
    1 if the display is occluded or set to 0 if the display is not
    occluded on the specified pasteboard. If the procedure does not
    return SS$_NORMAL, the contents of occlusion-state are undefined.

5.10  –  SMG$CONTROL_MODE

    The Control Mode routine controls the mode of the pasteboard.
    This includes buffering, minimal updating, whether the screen
    is cleared when the pasteboard is deleted, and whether tab
    characters are used for screen formatting.

    Format

      SMG$CONTROL_MODE  pasteboard-id [,new-mode] [,old-mode]

                        [,buffer-size]

5.10.1  –  Returns

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

5.10.2  –  Arguments

 pasteboard-id

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

    Specifies the pasteboard to be changed. The pasteboard-id
    argument is the address of an unsigned longword that contains
    the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 new-mode

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

    Specifies the new control settings to be used. The optional
    new-mode argument is the address of an unsigned longword that
    contains the mode settings. A bit set to 1 forces that mode to be
    employed; a bit set to 0 inhibits that mode of operation.

    Valid settings are as follows:

    SMG$M_BUF_ENABLED  Enables buffering.
    SMG$M_CLEAR_       Causes the Screen Management Facility to clear
    SCREEN             the screen when the program exits if you have
                       not previously deleted the pasteboard.
    SMG$M_IGNORE       Allows you to delete the pasteboard even if
                       batching is in effect.
    SMG$M_MINUPD       Enables minimal update (the default).
    SMG$M_NOTABS       Causes the Screen Management Facility not to
                       use tab characters to format the screen.
    SMG$M_PROTECT      Protect pasteboard operations from AST
                       interrupts (the default).
    SMG$M_RELEASE_PBD  Allows you to change the pasteboard size
                       (using the SMG$CHANGE_PBD_CHARACTERISTICS
                       routine) and prevents the Screen Management
                       Facility from modifying anything on the screen
                       outside of the smaller pasteboard.

    All other bits must be 0 and are reserved for future use by VSI.

 old-mode

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

    Receives the control settings that were in effect before calling
    this procedure. The optional old-mode argument is the address
    of an unsigned longword into which the former mode settings are
    written. A bit set to 1 indicates that the specified mode was
    employed; a bit set to 0 indicates that the mode was inhibited.

 buffer-size

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the size of the buffer in bytes. The optional buffer-
    size argument is the address of an unsigned word that contains
    the size of the buffer. The buffer-size argument is used when
    buffering mode is enabled (SMG$M_BUF_ENABLED). The default and
    minimum buffer size is 256 bytes. The maximum value is 65535. The
    buffer-size value depends on user authorization file (UAF) values
    and is maximized with the SYSGEN parameter MAXBUF.

5.11  –  SMG$COPY_VIRTUAL_DISPLAY

    The Copy a Virtual Display routine creates a copy of an
    existing virtual display and assigns to it a new virtual display
    identifier.

    Format

      SMG$COPY_VIRTUAL_DISPLAY  current-display-id ,new-display-id

5.11.1  –  Returns

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

5.11.2  –  Arguments

 current-display-id

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

    Display identifier of the virtual display to be replicated.
    The current-display-id argument is the address of the unsigned
    longword that contains the display identifier.

 new-display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the display identifier of the newly created virtual
    display. The new-display-id argument is the address of the
    unsigned longword that receives the new display identifier.

5.12  –  SMG$CREATE_KEY_TABLE

    The Create Key Table routine creates a table for key definitions.

    Format

      SMG$CREATE_KEY_TABLE  key-table-id

5.12.1  –  Returns

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

5.12.2  –  Argument

 key-table-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the identifier of the newly created key table. The key-
    table-id argument is the address of an unsigned longword into
    which the key table identifier is written.

5.13  –  SMG$CREATE_MENU

    The Fill the Virtual Display with a Menu routine displays
    menu choices in the virtual display indicated, starting at the
    specified row.

    Format

      SMG$CREATE_MENU  display-id ,choices [,menu-type]

                       [,flags] [,row] [,rendition-set]

                       [,rendition-complement]

5.13.1  –  Returns

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

5.13.2  –  Arguments

 display-id

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

    Display identifier of the virtual display in which the menu is
    created. The display-id argument is the address of an unsigned
    longword containing this identifier.

 choices

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

    Static array in which each element corresponds to an item to be
    displayed in the menu. The choices argument is the address of a
    descriptor pointing to this static array of character strings.
    Note that blank menu items are ignored.

 menu-type

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

    Optional bit mask specifying the type of menu to be displayed.
    The menu-type argument is the address of a longword bit mask that
    specifies this menu type. Valid values are as follows:

    SMG$K_BLOCK        The menu items are displayed in matrix format
                       (default).
    SMG$K_VERTICAL     Each menu item is displayed on its own line.
    SMG$K_HORIZONTAL   The menu items are displayed all on one line.

 flags

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

    Optional bit mask specifying the attributes to be used for the
    menu. The flags argument is the address of an unsigned longword
    that contains the flag. Valid values are as follows:

    SMG$M_DOUBLE_      Double-spaced rows of menu items. The default
    SPACE              is single spaced.
    SMG$M_FIXED_       Each menu item is in a fixed-length field. The
    FORMAT             field is the size of the largest menu item.
                       The default is compress.
    SMG$M_FULL_FIELD   The full field is highlighted when you move
                       within the menu using item keys. The default
                       is that menu items only are highlighted. If
                       you specify this flag value, it also implies
                       SMG$M_FIXED_FORMAT.
    SMG$M_WIDE_MENU    Wide characters are used in the menu items.
                       The default is normal sized characters.
    SMG$M_WRAP_MENU    The up arrow and down arrow keys cause the
                       menu to wrap when the cursor is on the first
                       or last rows of the menu.

 row

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

    Optional row number in the specified virtual display at which
    the first menu item is displayed. The row argument is the address
    of a signed longword that contains this row number. If row is
    omitted, the first row of the virtual display's scrolling region
    is used.

 rendition-set

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

    Attribute specifier. The optional rendition-set argument is the
    address of a longword bit mask in which each attribute set causes
    the corresponding attribute to be used when writing out the menu
    choices. The following attributes can be specified using the
    rendition-set argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

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

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to
    be complemented in the display. All of the attributes that can
    be specified with the rendition-set argument can be complemented
    with the rendition-complement argument. The display-id argument
    must be specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

5.14  –  SMG$CREATE_PASTEBOARD

    The Create a Pasteboard routine creates a pasteboard and returns
    its assigned pasteboard identifier.

    Format

      SMG$CREATE_PASTEBOARD  pasteboard-id [,output-device]

                             [,number-of-pasteboard-rows]

                             [,number-of-pasteboard-columns] [,flags]

                             [,type-of-terminal] [,device-name]

5.14.1  –  Returns

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

5.14.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the identifier of the newly created pasteboard. The
    pasteboard-id argument is the address of an unsigned longword
    into which the new pasteboard identifier is written.

 output-device

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

    Specifies the file specification or logical name to which the
    output associated with this pasteboard will be written. The
    output-device argument is the address of a descriptor that points
    to the name of the output device. If omitted, output is sent to
    SYS$OUTPUT.

 number-of-pasteboard-rows

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

    Receives the number of rows on the device specified in the
    output-device argument. The number-of-pasteboard-rows argument
    is the address of a signed longword into which is written the
    number of rows on the specified device, which will be the number
    of rows in the pasteboard.

 number-of-pasteboard-columns

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

    Receives the number of columns on the device specified in the
    output-device argument. The number-of-pasteboard-columns argument
    is the address of a signed longword into which the number of
    columns on the specified device is written.

 flags

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

    Specifies the attributes to be used in the pasteboard. The flags
    argument is the address of an unsigned longword that contains
    the flag. The default action is to clear the screen when the
    pasteboard is created.

    Valid values are as follows:

    SMG$M_KEEP_        The screen is not initially cleared. The
    CONTENTS           Screen Management Facility works best when
                       it can manage the entire screen. Therefore,
                       using SMG$M_KEEP_CONTENTS is discouraged.
    SMG$M_WORKSTATION  Calls DECterm to create a DECterm window if
                       the Screen Management Facility is running on
                       a workstation that is running DECwindows. If
                       it is not running on a workstation that is
                       running DECwindows, this flag is ignored.

 type-of-terminal

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

    Receives the SMG$ internal device type to which the output
    associated with this pasteboard will be written. The type-of-
    terminal argument is the address of an unsigned longword into
    which is written the terminal type.

    The returned values are as follows:

       SMG$K_UNKNOWN
       SMG$K_VTFOREIGN
       SMG$K_HARDCOPY
       SMG$K_VTTERMTABLE

    If a value other than SMG$K_VTTERMTABLE is returned, you must use
    SMG$SNAPSHOT to output the contents of the pasteboard.

 device-name

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

    Receives the device name of the device on which the output
    associated with this pasteboard is written. The device-name
    argument is the address of a descriptor into which is written
    the device name.

    If you specify the SMG$M_WORKSTATION value to the flags argument,
    this argument returns the DECwindows terminal device name created
    by the Screen Management Facility for this pasteboard. (You can
    then specify the device name in a call to SMG$CREATE_VIRTUAL_
    KEYBOARD to allow reading of input from the DECterm window.)
    Otherwise, the string specified by OUT_DEVICE is returned.

5.15  –  SMG$CREATE_SUBPROCESS

    The Create and Initialize a Subprocess routine creates a DCL
    subprocess and associates it with a virtual display.

    Format

      SMG$CREATE_SUBPROCESS  display-id [,AST-routine]

                             [,AST-argument] [,flags]

5.15.1  –  Returns

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

5.15.2  –  Arguments

 display-id

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

    Identifier of the virtual display with which the newly created
    subprocess is associated. The display-id argument is the address
    of an unsigned longword containing this identifier.

 AST-routine

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by value

    Optional AST routine to be called when the currently executing
    command completes. The AST-routine argument is the routine's
    procedure value.

    The AST routine is called with five parameters. The first
    parameter is a pointer to a data structure that contains the
    display-id, AST-argument, and the command-status values. The
    remaining four parameters for the AST routine are R0, R1, PC, and
    PSL. The following figure illustrates the AST-routine parameters
    and the data structure pointed to by the first parameter.

             Parameters to AST Routine               data structure
         +--------------------------------+       +------------------+
         |   address of data structure    |------>|    display-id    |
         +--------------------------------+       +------------------+
         |             R0                 |       |   AST-argument   |
         +--------------------------------+       +------------------+
         |             R1                 |       |  command-status  |
         +--------------------------------+       +------------------+
         |             PC                 |
         +--------------------------------+
         |            PSL                 |
         +--------------------------------+

    If the AST-routine argument is specified, the routine
    SMG$EXECUTE_COMMAND buffers any commands passed to it and
    executes them in order, calling the specified AST routine when
    each command completes. If the AST-routine argument is not
    specified, SMG$EXECUTE_COMMAND waits until the specified command
    completes before returning control to the user.

 AST-argument

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

    Optional argument you supply to the AST routine. The AST-argument
    parameter is an unsigned longword that contains the value to be
    passed to the AST routine.

 flags

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

    Optional argument you supply to SMG$CREATE_SUBPROCESS.
    SMG$CREATE_SUBPROCESS calls LIB$SPAWN to create the subprocess.
    The flags argument lets you control some of the flags used in
    that call. Flags available to SMG$CREATE_SUBPROCESS correspond to
    flags in LIB$SPAWN as follows:

    SMG$CREATE_        LIB$SPAWN
    SUBPROCESS Flag    Flag       Function

    SMG$M_TRUSTED      TRUSTED    If this bit is set, it indicates
                                  a SPAWN command on behalf of the
                                  application. If this bit is not
                                  set, it indicates that the SPAWN
                                  command originates from the user.
                                  SPAWN commands originating from
                                  users are disallowed in captive
                                  accounts (DCL).
    SMG$M_AUTHPRIV     AUTHPRIV   If this bit is set, the subprocess
                                  inherits the caller's authorized
                                  privileges. If this bit is clear,
                                  the spawned processes' authorized
                                  mask is set equal to the caller's
                                  current (active) privilege mask.
    SMG$M_SUBSYSTEM    SUBSYSTEM  If this bit is set, a spawned
                                  process inherits protected
                                  subsystem IDs for the duration
                                  of LOGINOUT.EXE (used to map the
                                  command line interpreter). The IDs
                                  will be removed in the process of
                                  transferring control to the command
                                  language interpreter (CLI) (as a
                                  user mode $RUNDWN is performed).
                                  If this bit is clear, LOGINOUT does
                                  not execute under the subsystem
                                  IDs.

    The default is that none of these bits is set. See online Help or
    the OpenVMS RTL Library (LIB$) Manual for a complete description
    of LIB$SPAWN, these flags, and the security consideration
    surrounding their use.

5.16  –  SMG$CREATE_VIEWPORT

    The Create a Virtual Viewport routine creates a viewport and
    associates it with a virtual display. The location and size of
    the viewport are specified by the caller.

    Format

      SMG$CREATE_VIEWPORT  display-id ,viewport-row-start

                           ,viewport-column-start

                           ,viewport-number-rows

                           ,viewport-number-columns

5.16.1  –  Returns

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

5.16.2  –  Arguments

 display-id

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

    Display identifier of the virtual display associated with the
    newly created viewport. The display-id argument is the address of
    an unsigned longword containing this identifier.

 viewport-row-start

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

    Row number in the virtual display that will become row 1 in the
    viewport. The viewport-row-start argument is the address of a
    signed longword containing the row number.

 viewport-column-start

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

    Column number in the virtual display that will become column 1 in
    the viewport. The viewport-column-start argument is the address
    of a signed longword containing the column number.

 viewport-number-rows

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

    Number of rows in the viewport. The viewport-number-rows argument
    is the address of a signed longword containing the number of rows
    in the newly created viewport.

 viewport-number-columns

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

    Number of columns in the viewport. The viewport-number-columns
    argument is the address of a signed longword containing the
    number of columns in the newly created viewport.

5.17  –  SMG$CREATE_VIRTUAL_DISPLAY

    The Create Virtual Display routine creates a virtual display and
    returns its assigned display identifier.

    Format

      SMG$CREATE_VIRTUAL_DISPLAY  number-of-rows ,number-of-columns

                                  ,display-id [,display-attributes]

                                  [,video-attributes]

                                  [,character-set]

5.17.1  –  Returns

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

5.17.2  –  Arguments

 number-of-rows

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

    Specifies the number of rows in the newly created virtual
    display. The number-of-rows argument is the address of a signed
    longword that contains the desired number of rows.

 number-of-columns

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

    Specifies the number of columns in the newly created virtual
    display. The number-of-columns argument is the address of a
    signed longword that contains the desired number of columns.

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the display-id of the newly created virtual display. The
    display-id argument is the address of an unsigned longword into
    which is written the display identifier.

 display-attributes

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

    Receives the current default display attributes. The optional
    display-attributes argument is the address of an unsigned
    longword into which the current display attributes are written.

    Valid values for display-attributes are as follows:

    SMG$M_BORDER       Specifies a bordered display. If omitted, the
                       display is not bordered.
    SMG$M_BLOCK_       Specifies a block-bordered display. If
    BORDER             omitted, the display is not bordered.
    SMG$M_DISPLAY_     Specifies that control characters such as
    CONTROLS           carriage return and line feed are displayed as
                       graphic characters, if your terminal supports
                       them.
    SMG$M_PROTECT_     Instructs the Screen Management Facility
    DISPLAY            to return an error (SMG$_DSPIN_USE) if an
                       SMG$ call is made from an AST routine that
                       interrupted an SMG$ call on the same display.
    SMG$M_TRUNC_ICON   Specifies that an icon (generally a diamond
                       shape) is displayed where truncation of a line
                       exceeding the width of the virtual display has
                       occurred.

 video-attributes

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

    Specifies the default rendition to be applied to all output in
    this virtual display unless overridden by a call to a specific
    output routine (for example, SMG$CHANGE_RENDITION). The video-
    attributes argument is the address of an unsigned longword that
    contains the video attributes mask.

    Valid values for this argument are as follows:

    SMG$M_BLINK        Displays blinking characters.
    SMG$M_BOLD         Displays characters in higher-than-normal
                       intensity.
    SMG$M_REVERSE      Displays characters in reverse video, that is,
                       using the opposite of the default rendition of
                       the virtual display.
    SMG$M_UNDERLINE    Displays underlined characters.
    SMG$M_INVISIBLE    Specifies invisible characters; that is, the
                       characters exist in the virtual display but do
                       not appear on the pasteboard.
    SMG$M_USER1        Displays user-defined attributes.
    through
    SMG$M_USER8

 character-set

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

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set specifier. Valid values
    are SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.

5.18  –  SMG$CREATE_VIRTUAL_KEYBOARD

    The Create a Virtual Keyboard routine creates a virtual keyboard
    and returns its assigned keyboard identifier.

    Format

      SMG$CREATE_VIRTUAL_KEYBOARD  keyboard-id [,input-device]

                                   [,default-filespec]

                                   [,resultant-filespec]

                                   [,recall-size]

5.18.1  –  Returns

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

5.18.2  –  Arguments

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the keyboard identifier of the newly created virtual
    keyboard. The keyboard-id argument is the address of an unsigned
    longword into which is written the keyboard identifier.

 input-device

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

    String containing the file specification or logical name of the
    file or terminal to be used for this virtual keyboard. The input-
    device argument is the address of a descriptor pointing to the
    file specification. If omitted, this defaults to SYS$INPUT.

 default-filespec

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

    String containing the default file specification. The default-
    filespec argument is the address of a descriptor pointing to the
    default file specification. If omitted, the null string is used.

    The default-filespec argument might be used to specify a default
    device and directory, leaving the input-device argument to supply
    the file name and type.

 resultant-filespec

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

    String into which the procedure writes the fully expanded file
    specification of the file used. The resultant-filespec argument
    is the address of a descriptor pointing to the string into which
    is written the file specification that was used.

 recall-size

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Number of input lines to be saved for later recall. The optional
    recall-size argument is the address of an unsigned byte
    containing the specified number of lines. A value of 0 turns
    off input line recall. By default, 20 lines are saved for later
    recall.

5.19  –  SMG$CURSOR_COLUMN

    The Return Cursor Column Position routine returns the virtual
    cursor's current column position in a specified virtual display.

    Format

      SMG$CURSOR_COLUMN  display-id

5.19.1  –  Returns

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

    SMG$CURSOR_COLUMN returns the current virtual cursor column
    position.

5.19.2  –  Argument

 display-id

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

    The display for which the column position is returned. The
    display-id argument is the address of an unsigned longword that
    contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

5.20  –  SMG$CURSOR_ROW

    The Return Cursor Row Position routine returns the virtual
    cursor's current row position in a specified virtual display.

    Format

      SMG$CURSOR_ROW  display-id

5.20.1  –  Returns

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

    SMG$CURSOR_ROW returns the current row position.

5.20.2  –  Argument

 display-id

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

    The display for which the row position is returned. The display-
    id argument is the address of an unsigned longword that contains
    the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

5.21  –  SMG$DEFINE_KEY

    The Perform a DEFINE/KEY Command routine performs the DEFINE/KEY
    command you provide.

    Format

      SMG$DEFINE_KEY  key-table-id ,command-string

5.21.1  –  Returns

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

5.21.2  –  Arguments

 key-table-id

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

    Identifies the key definition table for which the DEFINE/KEY
    command is to be performed. The key-table-id argument is the
    address of an unsigned longword that contains the key table
    identifier.

    The key table identifier is returned by SMG$CREATE_KEY_TABLE.

 command-string

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

    String containing the DEFINE/KEY command to be performed. The
    command-string argument is the address of a descriptor pointing
    to the command to be performed.

    The valid qualifiers for the DEFINE/KEY command are as follows:

    o  /TERMINATE

    o  /NOECHO

    o  /LOCK

    o  /IF_STATE

    o  /SET_STATE

    The following two restrictions apply to the DEFINE/KEY
    qualifiers:

    o  If you use the /LOCK qualifier, you must also use the /SET_
       STATE qualifier.

    o  If you use both the /SET_STATE and /TERMINATE qualifiers, you
       may not use /LOCK.

5.22  –  SMG$DELETE_CHARS

    The Delete Characters routine deletes characters in a virtual
    display.

    Format

      SMG$DELETE_CHARS  display-id ,number-of-characters ,start-row

                        ,start-column

5.22.1  –  Returns

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

5.22.2  –  Arguments

 display-id

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

    Identifies the virtual display from which characters are to be
    deleted. The display-id argument is the address of an unsigned
    longword that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 number-of-characters

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

    Specifies the number of characters to be deleted. The number-
    of-characters argument is the address of a signed longword that
    contains the number of characters to be deleted.

 start-row

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

    Specifies the row position at which to start the deletion. The
    start-row argument is the address of a signed longword that
    contains the row number at which to start the deletion.

 start-column

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

    Specifies the column position at which to start the deletion. The
    start-column argument is the address of a signed longword that
    contains the column position at which to start the deletion.

5.23  –  SMG$DELETE_KEY_DEF

    The Delete Key Definition routine deletes a key definition from
    the specified table of key definitions.

    Format

      SMG$DELETE_KEY_DEF  key-table-id ,key-name [,if-state]

5.23.1  –  Returns

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

5.23.2  –  Arguments

 key-table-id

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

    Identifies the key table from which the key definition is
    deleted. The key-table-id argument is the address of an unsigned
    longword that contains the key table identifier.

 key-name

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

    String containing the name of the key whose definition is to be
    deleted. The key-name argument is the address of a descriptor
    pointing to the key name. The key name is stripped of trailing
    blanks and converted to uppercase before use.

 if-state

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

    String containing a state name that further qualifies key-name.
    The if-state argument is the address of a descriptor pointing to
    the state name. If omitted, the null state is used. Thus if a key
    has several definitions depending on various values of if-state,
    this routine lets you delete only one of those definitions.

5.24  –  SMG$DELETE_LINE

    The Delete Line routine deletes lines from a virtual display.

    Format

      SMG$DELETE_LINE  display-id ,start-row [,number-of-rows]

5.24.1  –  Returns

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

5.24.2  –  Arguments

 display-id

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

    Identifies the virtual display from which lines are to be
    deleted. The display-id argument is the address of an unsigned
    longword that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

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

    Specifies the first line to be deleted from the virtual display.
    The start-row argument is the address of a signed longword that
    contains the number of the first line to be deleted.

 number-of-rows

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

    Specifies the number of lines to be deleted. The number-of-rows
    argument is the address of a signed longword that contains the
    number of lines to be deleted. If omitted, one line is deleted.

5.25  –  SMG$DELETE_MENU

    The End Access to a Menu in the Virtual Display routine ends
    access to the menu choices in the specified virtual display.

    Format

      SMG$DELETE_MENU  display-id [,flags]

5.25.1  –  Returns

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

5.25.2  –  Arguments

 display-id

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

    Identifier of the virtual display in which the menu choices are
    displayed. The display-id argument is the address of an unsigned
    longword containing this identifier.

 flags

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

    Optional bit mask specifying possible actions to take when
    deleting the menu. The flags argument is the address of an
    unsigned longword that contains the flag. At this time, the only
    valid value is SMG$M_ERASE_MENU. If this option is specified, all
    rows containing menu items are erased.

5.26  –  SMG$DELETE_PASTEBOARD

    The Delete Pasteboard routine deletes a pasteboard.

    Format

      SMG$DELETE_PASTEBOARD  pasteboard-id [,flags]

5.26.1  –  Returns

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

5.26.2  –  Arguments

 pasteboard-id

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

    Specifies the pasteboard to be deleted. The pasteboard-id
    argument is the address of an unsigned longword that contains
    the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 flags

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

    Optional bit mask specifying whether the screen is cleared after
    the specified pasteboard is deleted. The flags argument is the
    address of an unsigned longword that contains the flag. Valid
    values are as follows:

    0                  Does not clear the screen.
    SMG$M_ERASE_PBD    Clears the screen (default).
    SMG$M_IGNORE_      Deletes the pasteboard even if batching is in
    BATCHED            effect.

5.27  –  SMG$DELETE_SUBPROCESS

    The Terminate a Subprocess routine deletes a subprocess that was
    created with the SMG$CREATE_SUBPROCESS routine.

    Format

      SMG$DELETE_SUBPROCESS  display-id

5.27.1  –  Returns

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

5.27.2  –  Argument

 display-id

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

    Identifier of the virtual display associated with the subprocess
    being deleted. The display-id argument is the address of an
    unsigned longword that contains this virtual display identifier.

5.28  –  SMG$DELETE_VIEWPORT

    The Delete a Viewport routine deletes the specified viewport from
    any pasteboards to which it is pasted.

    Format

      SMG$DELETE_VIEWPORT  display-id

5.28.1  –  Returns

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

5.28.2  –  Argument

 display-id

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

    Identifier of the virtual display associated with the viewport to
    be deleted. The display-id argument is the address of an unsigned
    longword containing the display identifier.

5.29  –  SMG$DELETE_VIRTUAL_DISPLAY

    The Delete Virtual Display routine deletes a virtual display.

    Format

      SMG$DELETE_VIRTUAL_DISPLAY  display-id

5.29.1  –  Returns

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

5.29.2  –  Argument

 display-id

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

    Specifies the virtual display to be deleted. The display-id
    argument is the address of an unsigned longword that contains
    the display identifier.

    The display identifier display-id is returned by SMG$CREATE_
    VIRTUAL_DISPLAY.

5.30  –  SMG$DELETE_VIRTUAL_KEYBOARD

    The Delete Virtual Keyboard routine deletes a virtual keyboard.

    Format

      SMG$DELETE_VIRTUAL_KEYBOARD  keyboard-id

5.30.1  –  Returns

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

5.30.2  –  Argument

 keyboard-id

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

    Specifies the virtual keyboard to be deleted. The keyboard-id
    argument is the address of an unsigned longword that contains the
    keyboard identifier.

    The keyboard identifier is returned by SMG$CREATE_VIRTUAL_
    KEYBOARD.

5.31  –  SMG$DEL_TERM_TABLE

    The Delete Terminal Table routine terminates access to a private
    TERMTABLE.EXE and frees the associated virtual address space.

    Format

      SMG$DEL_TERM_TABLE

5.31.1  –  Returns

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

5.31.2  –  Arguments

    None.

5.32  –  SMG$DISABLE_BROADCAST_TRAPPING

    The Disable Broadcast Trapping routine disables trapping of
    broadcast messages for the specified terminal.

    Format

      SMG$DISABLE_BROADCAST_TRAPPING  pasteboard-id

5.32.1  –  Returns

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

5.32.2  –  Argument

 pasteboard-id

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

    Specifies the pasteboard for the terminal to be affected. The
    pasteboard-id argument is the address of an unsigned longword
    that contains the pasteboard identifier.

5.33  –  SMG$DISABLE_UNSOLICITED_INPUT

    The Disable Unsolicited Input routine disables the trapping of
    unsolicited input.

    Format

      SMG$DISABLE_UNSOLICITED_INPUT  pasteboard-id

5.33.1  –  Returns

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

5.33.2  –  Argument

 pasteboard-id

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

    Specifies the keyboard (associated with the specified pasteboard)
    for which unsolicited input is being disabled. The pasteboard-id
    argument is the address of an unsigned longword that contains the
    pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

5.34  –  SMG$DRAW_CHAR

    The Draw a Character in a Virtual Display routine draws a
    character at the specified position in a virtual display.

    Format

      SMG$DRAW_CHAR  display-id ,flags [,row] [,column]

                     [,rendition-set] [,rendition-complement]

5.34.1  –  Returns

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

5.34.2  –  Arguments

 display-id

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

    Identifier of the virtual display. The display-id argument is the
    address of an unsigned longword containing this identifier.

 flags

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

    Optional bit mask indicating the character to be drawn. The flags
    argument is the address of an unsigned longword that contains the
    flag. The flags argument accepts the following character values:

    o  SMG$M_UP

    o  SMG$M_DOWN

    o  SMG$M_LEFT

    o  SMG$M_RIGHT

    Note that you may perform a logical OR operation to draw T
    characters, corner characters, cross characters, and so forth.
    A value of 0 draws a diamond character.

 row

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

    Optional row number specifying the row position at which the
    specified character is drawn. The row argument is the address of
    a signed longword containing the row number. If row is omitted,
    the character is drawn at the row position of the current virtual
    cursor.

 column

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

    Optional column number specifying the column position at which
    the specified character is drawn. The column argument is the
    address of a signed longword containing the column number. If
    column is omitted, the character is drawn at the column position
    of the current virtual cursor.

 rendition-set

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

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

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

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to
    be complemented in the display. All of the attributes that can
    be specified with the rendition-set argument can be complemented
    with the rendition-complement argument. The display-id argument
    must be specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

5.35  –  SMG$DRAW_LINE

    The Draw a Line routine draws a horizontal or vertical line.

    Format

      SMG$DRAW_LINE  display-id ,start-row ,start-column

                     ,end-row ,end-column [,rendition-set]

                     [,rendition-complement]

5.35.1  –  Returns

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

5.35.2  –  Arguments

 display-id

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

    Specifies the virtual display on which the line is to be drawn.
    The display-id argument is the address of an unsigned longword
    that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

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

    Specifies the row at which to begin drawing the line. The start-
    row argument is the address of a signed longword that contains
    the row number at which to begin drawing the line.

 start-column

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

    Specifies the column at which to begin drawing the line. The
    start-column argument is the address of a signed longword that
    contains the column number at which to begin drawing the line.

 end-row

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

    Specifies the row at which the drawn line ends. The end-row
    argument is the address of a signed longword that contains the
    row number at which the drawn line ends.

 end-column

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

    Specifies the column at which the drawn line ends. The end-column
    argument is the address of a signed longword that contains the
    column number at which the drawn line ends.

 rendition-set

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

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

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

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to
    be complemented in the display. All of the attributes that can
    be specified with the rendition-set argument can be complemented
    with the rendition-complement argument. The display-id argument
    must be specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

5.36  –  SMG$DRAW_RECTANGLE

    The Draw a Rectangle routine draws a rectangle.

    Format

      SMG$DRAW_RECTANGLE  display-id ,start-row ,start-column

                          ,end-row ,end-column [,rendition-set]

                          [,rendition-complement]

5.36.1  –  Returns

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

5.36.2  –  Arguments

 display-id

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

    Specifies the virtual display on which the rectangle is to be
    drawn. The display-id argument is the address of an unsigned
    longword that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

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

    Specifies the row number of the top left corner of the rectangle.
    The start-row argument is the address of a signed longword that
    contains the row number of the top left corner of the rectangle.

 start-column

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

    Specifies the column number of the top left corner of the
    rectangle. The start-column argument is the address of a signed
    longword that contains the column number of the top left corner
    of the rectangle.

 end-row

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

    Specifies the row number of the bottom right corner of the
    rectangle. The end-row argument is the address of a signed
    longword that contains the row number of the bottom right corner
    of the rectangle.

 end-column

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

    Specifies the column number of the bottom right corner of the
    rectangle. The end-column argument is the address of a signed
    longword that contains the column number of the bottom right
    corner of the rectangle.

 rendition-set

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

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

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

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to
    be complemented in the display. All of the attributes that can
    be specified with the rendition-set argument can be complemented
    with the rendition-complement argument. The display-id argument
    must be specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

5.37  –  SMG$ENABLE_UNSOLICITED_INPUT

    The Enable Unsolicited Input routine detects unsolicited input
    and calls an AST routine in response.

    Format

      SMG$ENABLE_UNSOLICITED_INPUT  pasteboard-id ,AST-routine

                                    [,AST-argument]

5.37.1  –  Returns

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

5.37.2  –  Arguments

 pasteboard-id

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

    Specifies the pasteboard for which unsolicited input is being
    enabled. The pasteboard-id argument is the address of an unsigned
    longword that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_VIRTUAL_
    PASTEBOARD.

 AST-routine

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       read only
    mechanism:    by value

    AST routine to be called upon receipt of unsolicited input at
    the terminal. The AST-routine argument contains the routine's
    procedure value. SMG$ENABLE_UNSOLICITED_INPUT detects the
    presence of unsolicited input and calls the AST routine with
    six arguments: the pasteboard-id, the AST-argument, R0, R1, PC,
    and PSL (on VAX systems) or PS (on Alpha systems).

 AST-argument

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

    A value to be passed to the AST routine. The AST-argument
    argument contains the value to be passed to the AST routine.

5.38  –  SMG$END_DISPLAY_UPDATE

    The End Display Update routine ends update batching for a virtual
    display.

    Format

      SMG$END_DISPLAY_UPDATE  display-id

5.38.1  –  Returns

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

5.38.2  –  Argument

 display-id

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

    Specifies the virtual display to be affected. The display-id
    argument is the address of an unsigned longword that contains the
    display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

5.39  –  SMG$END_PASTEBOARD_UPDATE

    The End Pasteboard Update routine ends update batching for a
    pasteboard.

    Format

      SMG$END_PASTEBOARD_UPDATE  pasteboard-id

5.39.1  –  Returns

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

5.39.2  –  Argument

 pasteboard-id

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

    Specifies the pasteboard on which the batch count is to be
    decremented. The pasteboard-id argument is the address of an
    unsigned longword that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
    If the batch count reaches 0, all buffered output for the
    specified pasteboard is written out.

5.40  –  SMG$ERASE_CHARS

    The Erase Characters routine erases characters in a virtual
    display by replacing them with blanks.

    Format

      SMG$ERASE_CHARS  display-id ,number-of-characters ,start-row

                       ,start-column

5.40.1  –  Returns

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

5.40.2  –  Arguments

 display-id

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

    Specifies the virtual display from which characters will be
    erased. The display-id argument is the address of an unsigned
    longword that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 number-of-characters

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

    Specifies the number of characters to be replaced with blanks.
    The number-of-characters argument is the address of a signed
    longword that contains the number of characters to be replaced
    with blanks.

 start-row

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

    Specifies the row on which the erase operation begins. The start-
    row argument is the address of a signed longword that contains
    the number of the row at which the erasure is to begin.

 start-column

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

    Specifies the column on which the erase operation begins. The
    start-column argument is the address of a signed longword that
    contains the number of the column at which the erasure is to
    begin.

5.41  –  SMG$ERASE_COLUMN

    The Erase Column from Display routine erases the specified
    portion of the virtual display from the given position to the
    end of the column.

    Format

      SMG$ERASE_COLUMN  display-id [,start-row] [,column-number]

                        [,end-row]

5.41.1  –  Returns

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

5.41.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the virtual display to be affected. The display-id
    argument is the address of an unsigned longword containing this
    virtual display identifier.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Optional line number at which the erase operation begins. The
    start-row argument is the address of a signed longword that
    contains the specified line number. If this argument is omitted,
    the column-number argument is ignored and the erase operation
    begins at the current location of the virtual cursor for that
    virtual display.

 column-number

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Optional column number at which the erase operation begins.
    The column-number argument is the address of a signed longword
    that contains the specified column number. If this argument
    is omitted, the start-row argument is ignored and the erase
    operation begins at the current location of the virtual cursor
    for that virtual display.

 end-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Optional row number at which the erase operation ends. The end-
    row argument is the address of a signed longword that contains
    the specified row number.

5.42  –  SMG$ERASE_DISPLAY

    The Erase Virtual Display routine erases all or part of a virtual
    display by replacing text characters with blanks.

    Format

      SMG$ERASE_DISPLAY  display-id [,start-row] [,start-column]

                         [,end-row] [,end-column]

5.42.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.42.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display to be erased. The display-id
    argument is the address of an unsigned longword that contains
    the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the row at which the erase operation begins. The start-
    row argument is the address of a signed longword that contains
    the number of the row at which the erasure begins.

    If the start-row argument is not specified, start-column is also
    ignored and the entire virtual display is erased. If you do not
    specify start-row and start-column, then end-row and end-column
    are ignored and the entire virtual display is erased.

 start-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column at which the erase operation begins. The
    start-column argument is the address of a signed longword that
    contains the number of the column at which the erasure begins.

    If the start-column argument is not specified, start-row is also
    ignored and the entire virtual display is erased. If you do not
    specify start-row and start-column, then end-row and end-column
    are ignored and the entire virtual display is erased.

 end-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the row at which the erase operation ends; that is, the
    last row to be erased. The end-row argument is the address of a
    signed longword that contains the number of the last row to be
    erased.

    If the end-row argument is not specified, end-column is also
    ignored and all remaining rows in the display are erased.

 end-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column at which the erase operation ends; that
    is, the last column to be erased. The end-column argument is the
    address of a signed longword that contains the number of the last
    column to be erased.

    If the end-column argument is not specified, end-row is also
    ignored and all remaining columns in the display are erased.

5.43  –  SMG$ERASE_LINE

    The Erase Line routine erases all or part of a line in a virtual
    display.

    Format

      SMG$ERASE_LINE  display-id [,start-row] [,start-column]

5.43.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.43.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display to be affected. The display-id
    argument is the address of an unsigned longword that contains the
    display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the line at which the erase operation starts. The
    start-row argument is the address of a signed longword that
    contains the number of the row at which the erasure starts. If
    omitted, start-column is also ignored and the current cursor
    position is used.

 start-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column at which the erase operation starts. The
    start-column argument is the address of a signed longword that
    contains the number of the column at which the erasure starts.
    If omitted, start-row is also ignored and the current cursor
    position is used.

5.44  –  SMG$ERASE_PASTEBOARD

    The Erase Pasteboard routine erases the contents of a pasteboard.

    Format

      SMG$ERASE_PASTEBOARD  pasteboard-id

5.44.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.44.2  –  Argument

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard to be erased. The pasteboard-id
    argument is the address of an unsigned longword that contains
    the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

5.45  –  SMG$EXECUTE_COMMAND

    The Execute Command in a Subprocess routine executes the
    specified command in the subprocess created with the SMG$CREATE_
    SUBPROCESS routine.

    Format

      SMG$EXECUTE_COMMAND  display-id ,command-desc [,flags]

                           [,ret-status]

5.45.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.45.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Display identifier of the virtual display with which the
    subprocess is associated. The display-id argument is the address
    of an unsigned longword containing this identifier.

 command-desc

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Command string. The command-desc argument is the address of a
    descriptor pointing to the command string.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies optional behavior. The flags
    argument is the address of an unsigned longword that contains the
    flag. The valid values for flags are as follows:

    SMG$M_DATA_FOLLOWS   Input data follows. The next call to
                         SMG$EXECUTE_COMMAND contains input data
                         for the currently executing command. Do not
                         specify this value if this is the last input
                         data item. If you do specify this value,
                         ret-status is not returned.
    SMG$M_SEND_EOF       Send end-of-file marker. The end-of-file
                         marker is sent to the subprocess.

 ret-status

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Optional status of the executed command, provided that the
    commands are not being buffered. The ret-status argument is the
    address of an unsigned longword containing this status.

5.46  –  SMG$FIND_CURSOR_DISPLAY

    The Find Display that Contains the Cursor routine returns the
    identifier of the most recently pasted virtual display that
    contains the physical cursor.

    Format

      SMG$FIND_CURSOR_DISPLAY  pasteboard-id ,display-id

                               [,pasteboard-row] [,pasteboard-column]

5.46.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.46.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard in which the physical cursor is to be
    found. The pasteboard-id argument is the address of an unsigned
    longword that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the identifier of the display in which the physical
    cursor was found. The display-id argument is the address of an
    unsigned longword into which the display identifier is written.

 pasteboard-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    The row position at which to begin the search for the physical
    cursor. The optional pasteboard-row argument is the address of
    a signed longword containing the pasteboard row. You can use
    pasteboard-row instead of the physical cursor row.

 pasteboard-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    The column position at which to begin the search for the physical
    cursor. The optional pasteboard-column argument is the address of
    a signed longword containing the pasteboard column. You can use
    pasteboard-column instead of the physical cursor column.

5.47  –  SMG$FLUSH_BUFFER

    The Flush Buffer routine flushes all buffered output to the
    terminal.

    Format

      SMG$FLUSH_BUFFER  pasteboard-id

5.47.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.47.2  –  Argument

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard to be flushed. The pasteboard-id
    argument is the address of an unsigned longword that contains
    the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

5.48  –  SMG$FLUSH_DISPLAY_UPDATE

    The Flush Display Update routine flushes any update batching to
    the screen and leaves the update batching in effect.

    Format

      SMG$FLUSH_DISPLAY_UPDATE  display-id

5.48.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.48.2  –  Argument

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display to be affected. The display-id
    argument is the address of an unsigned longword that contains the
    display identifier.

    The display argument is returned by SMG$CREATE_VIRTUAL_DISPLAY.

5.49  –  SMG$GET_BROADCAST_MESSAGE

    The Get Broadcast Message routine determines whether a message
    has been broadcast to the pasteboard and returns the message.

    Format

      SMG$GET_BROADCAST_MESSAGE  pasteboard-id [,message]

                                 [,message-length] [,message-type]

5.49.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.49.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard to be checked for the presence of a
    broadcast message. The pasteboard-id argument is the address of
    an unsigned longword that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 message

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    A string that receives the broadcast message, if such a message
    is available. The message argument is the address of a descriptor
    that points to the string into which the message text is written.
    If this argument is omitted, the broadcast message is discarded.

 message-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the actual length of the broadcast message. The message-
    length argument is the address of an unsigned word into which is
    written the length of the message.

 message-type

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the type of broadcast message. The message-type argument
    is the address of an unsigned word into which is written the type
    of message. Values for message-type are defined by the $MSGDEF
    library definition. If the value for message-type is not MSG$_
    TRMBRDCST, the condition value returned is SMG$_NOBRDMSG.

5.50  –  SMG$GET_CHAR_AT_PHYSICAL_CURSOR

    The Return Character at Cursor routine returns the character at
    the current physical cursor position.

    Format

      SMG$GET_CHAR_AT_PHYSICAL_CURSOR  pasteboard-id ,character-code

                                       [,rendition] [,user-rendition]

5.50.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.50.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard from which to retrieve the character.
    The pasteboard-id argument is the address of an unsigned longword
    that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 character-code

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       write only
    mechanism:    by reference

    Returned character code. The character-code argument is the
    address of an unsigned byte into which is written the character's
    ASCII code.

 rendition

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the rendition code associated with the character code
    returned by the character-code argument. The rendition argument
    is the address of an unsigned byte into which is written the
    rendition code.

 user-rendition

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the user rendition code associated with the character
    code returned by the character-code argument. The user-rendition
    argument is the address of an unsigned byte into which is written
    the user rendition code.

5.51  –  SMG$GET_DISPLAY_ATTR

    The Get Display Attributes routine receives the attributes
    associated with a virtual display.

    Format

      SMG$GET_DISPLAY_ATTR  display-id [,height] [,width]

                            [,display-attributes] [,video-attributes]

                            [,character-set] [,flags]

5.51.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.51.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display for which information is requested.
    The display-id argument is the address of an unsigned longword
    that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 height

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Receives the number of rows in the display. The optional height
    argument is the address of a signed longword into which the
    height is written.

 width

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Receives the number of columns in the display. The optional
    width argument is the address of a signed longword into which
    is written the number of columns in the display.

 display-attributes

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the current default display attributes. The optional
    display-attributes argument is the address of an unsigned
    longword into which the current display attributes are written.

    Valid values for display-attributes are as follows:

    SMG$M_BORDER       Specifies a bordered display. If omitted, the
                       display is not bordered.
    SMG$M_BLOCK_       Specifies a block bordered display. If
    BORDER             omitted, the display is not bordered.
    SMG$M_DISPLAY_     Specifies that control characters such as
    CONTROLS           carriage return and line feed are displayed as
                       graphic characters, if your terminal supports
                       them.
    SMG$M_TRUNC_ICON   Specifies that an icon (generally a diamond
                       shape) is displayed where truncation of a line
                       exceeding the width of the virtual display has
                       occurred.

 video-attributes

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the current default video attributes. The optional
    video-attributes argument is the address of an unsigned longword
    into which the current video attributes are written.

    Valid video attributes are as follows:

    SMG$M_BLINK        Displays blinking characters.
    SMG$M_BOLD         Displays characters in higher-than-normal
                       intensity.
    SMG$M_REVERSE      Displays characters in reverse video; that is,
                       using the opposite of the default rendition of
                       the virtual display.
    SMG$M_UNDERLINE    Displays underlined characters.
    SMG$M_INVISIBLE    Specifies invisible characters; that is, the
                       characters exist in the virtual display but do
                       not appear on the pasteboard.
    SMG$M_USER1        Displays user-defined attributes.
    through
    SMG$M_USER8

 character-set

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the default character set for all text in this virtual
    display. The optional character-set argument is the address of an
    unsigned longword that specifies the character set. Valid values
    are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Optional bit mask specifying attributes of the specified display.
    The flags argument is the address of an unsigned longword
    containing the flag. Valid values for flags are as follows:

    SMG$M_SUBPROCESS   Display has a subprocess attached to it.
    SMG$M_MENU         Display contains a menu.
    SMG$M_VIEWPORT     Display contains a viewport.

5.52  –  SMG$GET_KEYBOARD_ATTRIBUTES

    The Get Keyboard Attributes routine gets information about a
    virtual keyboard and leaves it in a user-supplied area: the
    keyboard information table (KIT).

    Format

      SMG$GET_KEYBOARD_ATTRIBUTES  keyboard-id ,keyboard-info-table

                                   ,keyboard-info-table-size

5.52.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.52.2  –  Arguments

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Keyboard identifier. The keyboard-id argument is the address of
    an unsigned longword containing the identifier of the virtual
    keyboard from which to read.

    Create a virtual keyboard by calling the SMG$CREATE_VIRTUAL_
    KEYBOARD routine.

 keyboard-info-table

    OpenVMS usage:unspecified
    type:         unspecified
    access:       write only
    mechanism:    by reference, array reference

    Receives the keyboard attributes. The keyboard-info-table
    argument is the address of a data block into which the keyboard
    attributes are written.

    The KIT is a byte block whose size and field references are
    described in $SMGDEF. It is the caller's responsibility to
    allocate the correct size block and to pass its address to this
    routine.

    The values in the keyboard-info-table can be accessed through the
    following symbolic names:

    SMG$L_DEV_CHAR     Device characteristics (longword)
    SMG$L_DEV_DEPEND   Specific characteristics 1 (longword)
    SMG$L_DEV_DEPEND2  Specific characteristics 2 (longword)
    SMG$L_DEV_DEPEND3  Specific characteristics 3 (longword)
    SMG$B_DEV_CLASS    Device class (byte) - for example, DC$_TERM
    SMG$B_RECALL_NUM   Size of recall buffer (byte)*
    SMG$B_DEVTYPE      Physical device type (byte) - for example,
                       TT$_VT100
    SMG$B_TYPEAHD_     First character in type-ahead buffer (byte)*
    CHAR
    SMG$W_NUM_COLUMNS  Terminal width (word)
    SMG$W_TYPEAHD_CNT  Number of characters in type-ahead buffer
                       (word)*

    Items marked with an asterisk (*) will be zero unless the device
    is a terminal (DEVCLASS = DC$_TERM).

 keyboard-info-table-size

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Size of the keyboard information table. The keyboard-info-table-
    size argument is the address of an unsigned longword containing
    the size of the KIT in bytes.

    The size you specify must be exact. You can specify this size
    with the symbolic constant SMG$C_KEYBOARD_INFO_BLOCK.

5.53  –  SMG$GET_KEY_DEF

    The Get Key Definition routine returns the key definition for a
    specified key.

    Format

      SMG$GET_KEY_DEF  key-table-id ,key-name [,if-state]

                       [,attributes] [,equivalence-string]

                       [,state-string]

5.53.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.53.2  –  Arguments

 key-table-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the key table from which you are extracting a
    definition. The key-table-id argument is the address of an
    unsigned longword that contains the key table identifier.

    The key table identifier is returned by SMG$CREATE_KEY_TABLE.

 key-name

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Specifies the name of the key associated with the definition. The
    key-name argument is the address of a descriptor pointing to the
    key name.

 if-state

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Specifies the current state name in effect after the key is
    pressed. The if-state argument is the address of a descriptor
    pointing to the state name.

    See SMG$ADD_KEY_DEF for more information.

 attributes

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the attributes bit mask for this key definition. The
    attributes argument is the address of a longword into which is
    written the bit mask describing the key's attributes.

    Valid values are as follows:

    SMG$M_KEY_NOECHO   If set, this bit specifies that equiv_string
                       is not to be echoed when this key is pressed.
                       If clear, equiv_string is echoed. If SMG$M_
                       KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is
                       ignored.
    SMG$M_KEY_         If set, this bit specifies that when this key
    TERMINATE          is pressed (as qualified by if-state), the
                       input line is complete and more characters
                       should not be accepted. If clear, more
                       characters may be accepted.
    SMG$M_KEY_         If set, and if state-string is specified, the
    LOCKSTATE          state name specified by state-string remains
                       at the current state until explicitly changed
                       by a subsequent keystroke whose definition
                       includes a state-string. If clear, the state
                       name specified by state-string remains in
                       effect only for the next defined key stroke.
    SMG$M_KEY_         If set, this bit specifies that this key
    PROTECTED          definition cannot be modified or deleted.
                       If clear, the key definition can be modified
                       or deleted.

 equivalence-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Receives the equivalence string for this key definition. The
    equivalence-string argument is the address of a descriptor
    pointing to the string into which is written the equivalence
    string.

 state-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Receives the new state name, if any, which is set by this
    key definition. The state-string argument is the address of a
    descriptor pointing to the string into which is written the new
    state string.

5.54  –  SMG$GET_NUMERIC_DATA

    The Get Numeric Terminal Data routine accesses TERMTABLE.EXE and
    returns the value associated with a specified Boolean or numeric
    capability.

    Format

      SMG$GET_NUMERIC_DATA  termtable-address ,request-code

                            ,buffer-address

5.54.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.54.2  –  Arguments

 termtable-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the address of the TERMTABLE entry for the desired
    terminal. The termtable-address argument is the address of an
    unsigned longword that contains the address of the terminal
    capabilities table (TERMTABLE).

    Before calling SMG$GET_NUMERIC_DATA, you must obtain this
    terminal table address by calling either SMG$INIT_TERM_TABLE
    or SMG$INIT_TERM_TABLE_BY_TYPE.

 request-code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Request code that specifies the desired capability. The request-
    code argument is an unsigned longword constant containing this
    request code. The request code is of the form SMG$K_code, where
    code corresponds to a keyword in the terminal capabilities table
    (TERMTABLE), for example, ANSI_CRT. The SMG$K_code constants can
    be found in the library supplied by OpenVMS, $SMGTRMPTR.

 buffer-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Address of the first byte of the longword to which SMG$GET_
    NUMERIC_DATA writes the numeric capability data. The buffer-
    address argument is an unsigned longword that contains the
    address of this buffer.

5.55  –  SMG$GET_PASTEBOARD_ATTRIBUTES

    The Get Pasteboard Attributes routine gets pasteboard attributes
    and stores them in the pasteboard information table.

    Format

      SMG$GET_PASTEBOARD_ATTRIBUTES  pasteboard-id

                                     ,pasteboard-info-table

                                     ,pasteboard-info-table-size

5.55.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.55.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard for which information is requested. The
    pasteboard-id argument is the address of an unsigned longword
    that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 pasteboard-info-table

    OpenVMS usage:unspecified
    type:         unspecified
    access:       write only
    mechanism:    by reference, array reference

    Receives the pasteboard attributes. The pasteboard-info-table
    argument is the address of a data structure into which are
    written the pasteboard attributes.

    The values in the pasteboard-info-table can be accessed through
    the following symbolic names:

    SMG$L_DEVCHAR    Device characteristics (longword).
    SMG$L_DEVDEPEND  Specific characteristics 1 (longword).
    SMG$L_           Specific characteristics 2 (longword).
    DEVDEPEND2
    SMG$L_           Specific characteristics 3 (longword).
    DEVDEPEND3
    SMG$B_DEVCLASS   Device class (byte)-for example, DC$_TERM.
    SMG$B_SMG_       Internal SMG device type (byte). The four
    DEVTYPE          possible values for SMG$B_SMG_DEVTYPE are as
                     follows:

                        SMG$K_UNKNOWN
                        SMG$K_VTFOREIGN
                        SMG$K_HARDCOPY
                        SMG$K_VTTERMTABLE

    SMG$B_PHY_       Physical device type (byte)-for example, TT$_
    DEVTYPE          VT100. The possible values for SMG$B_PHY_DEVTYPE
                     are defined in $TTDEF in STARLET.
    SMG$B_ROWS       Number of rows on pasteboard (byte).
    SMG$W_WIDTH      Pasteboard width (word).
    SMG$B_COLOR      Background color setting (byte). Valid values
                     for SMG$B_COLOR are as follows:
                     SMG$C_COLOR_        Unknown background color
                     UNKNOWN
                     SMG$C_COLOR_WHITE   Light background
                     SMG$C_COLOR_BLACK   Dark background
                     SMG$C_COLOR_BLUE    Blue background
                     SMG$C_COLOR_CYAN    Cyan (green-blue) background
                     SMG$C_COLOR_GREEN   Green background
                     SMG$C_COLOR_        Magenta background
                     MAGENTA
                     SMG$C_COLOR_RED     Red background
                     SMG$C_COLOR_        Yellow background
                     YELLOW
                     SMG$C_COLOR_LIGHT   White background
                     SMG$C_COLOR_DARK    Black background
                     SMG$C_COLOR_USER1   User-defined background 1
                     SMG$C_COLOR_USER2   User-defined background 2
    SMG$B_PARITY     Parity attributes (byte)-this field is zero if
                     the pasteboard is not a terminal.
    SMG$W_SPEED      Terminal speed (word)-this field is zero if the
                     pasteboard is not a terminal.
    SMG$W_FILL       Fill characteristics (word)-this field is zero
                     if the pasteboard is not a terminal.
    SMG$W_PHYS_      Pasteboard row containing physical cursor
    CURSOR_ROW       (word).
    SMG$W_PHYS_      Pasteboard column containing physical cursor
    CURSOR_COL       (word).
    SMG$L_CURSOR_    Display identifier of topmost display containing
    DID              physical cursor (longword).

 pasteboard-info-table-size

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the number of bytes in the pasteboard information
    table. The pasteboard-info-table-size argument is the address
    of an unsigned longword that contains the size (in bytes) of the
    pasteboard information table.

    The size you specify must be exact. You can specify this size
    with the symbolic constant SMG$C_PASTEBOARD_INFO_BLOCK.

5.56  –  SMG$GET_PASTING_INFO

    Provided that the specified virtual display is currently pasted,
    the Return Pasting Information routine returns the row and column
    of the pasting.

    Format

      SMG$GET_PASTING_INFO  display-id ,pasteboard-id ,flags

                            [,pasteboard-row] [,pasteboard-column]

5.56.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.56.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the virtual display to be examined. The display-id
    argument is the address of an unsigned longword containing the
    identifier of this virtual display.

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the pasteboard on which the virtual display is
    pasted. The pasteboard-id argument is the address of an unsigned
    longword containing the identifier of this pasteboard.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Bit mask indicating the status of the specified virtual display
    with respect to the specified pasteboard. The flags argument is
    the address of an unsigned longword that contains the flag. Valid
    values for flags are as follows:

    0                  The virtual display is not pasted to the
                       specified pasteboard.
    SMG$M_DISPLAY_     The virtual display specified by display-id
    PASTED             is pasted to the pasteboard specified by the
                       pasteboard-id argument.

 pasteboard-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Row of the pasteboard that contains row 1 of the specified
    virtual display. The optional pasteboard-row argument is the
    address of a signed longword containing the number of the
    pasteboard row that contains the first row of the virtual
    display.

 pasteboard-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Column of the pasteboard that contains column 1 of the specified
    virtual display. The optional pasteboard-column argument is
    the address of a signed longword containing the number of the
    pasteboard column that contains the first column of the virtual
    display.

5.57  –  SMG$GET_TERM_DATA

    The Get Terminal Data routine accesses TERMTABLE.EXE and returns
    the character sequence that causes a terminal to perform a
    specified operation.

    Format

      SMG$GET_TERM_DATA  termtable-address ,request-code

                         ,maximum-buffer-length ,return-length

                         ,capability-data [,input-argument-vector]

5.57.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.57.2  –  Arguments

 termtable-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the address of the TERMTABLE entry for the desired
    terminal. The termtable-address argument is the address of an
    unsigned longword that contains the address of the terminal
    capabilities table (TERMTABLE).

    The TERMTABLE address is returned by SMG$INIT_TERM_TABLE or
    SMG$INIT_TERM_TABLE_BY_TYPE.

 request-code

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Longword constant of the form SMG$K_code, where code is the name
    of the desired capability field. The request-code argument is
    the address of a signed longword that contains the request code.
    The SMG$K_code constants can be found in the library supplied by
    OpenVMS, $SMGTRMPTR.

 maximum-buffer-length

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Maximum length of the buffer into which the requested capability
    data is written. The maximum-buffer-length argument is the
    address of a signed longword that contains the maximum number
    of bytes that can be written into the buffer.

 return-length

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Receives the number of bytes actually written into the buffer.
    The return-length argument is the address of a signed longword
    into which is written the number of bytes transferred into the
    buffer.

 capability-data

    OpenVMS usage:unspecified
    type:         unspecified
    access:       by reference, array reference
    mechanism:    0

    Address of the first byte of the buffer which is to receive
    the capability data. The capability-data argument contains the
    address of the buffer.

 input-argument-vector

    OpenVMS usage:vector_longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference, array reference

    Address of a list of longwords used for capabilities that require
    a variable number of arguments, and for those that require
    substitution or arithmetic operations on an argument. The input-
    argument-vector argument is the address of an array of unsigned
    longwords that contains capability arguments. The first longword
    must contain the number of arguments that follow.

5.58  –  SMG$GET_VIEWPORT_CHAR

    The Get Characteristics of Display Viewport routine returns the
    characteristics of the specified viewport.

    Format

      SMG$GET_VIEWPORT_CHAR  display-id [,viewport-row-start]

                             [,viewport-column-start]

                             [,viewport-number-rows]

                             [,viewport-number-columns]

5.58.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.58.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the virtual display associated with the viewport.
    The display-id argument is the address of an unsigned longword
    containing this identifier.

 viewport-row-start

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Optional argument that receives the starting row number of the
    viewport. The viewport-row-start argument is the address of a
    signed longword that receives this row number.

 viewport-column-start

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Optional argument that receives the starting column number of
    the specified viewport. The viewport-column-start argument is the
    address of a signed longword that receives this column number.

 viewport-number-rows

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Optional argument that receives the number of rows in the
    specified viewport. The viewport-number-rows argument is the
    address of a signed longword that receives this number.

 viewport-number-columns

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Optional argument that receives the number of columns in the
    specified viewport. The viewport-number-columns argument is the
    address of a signed longword that receives this number.

5.59  –  SMG$HOME_CURSOR

    The Home Cursor routine moves the virtual cursor to the specified
    corner of a virtual display.

    Format

      SMG$HOME_CURSOR  display-id [,position-code]

5.59.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.59.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display in which the virtual cursor is
    moved. The display-id argument is the address of a longword that
    contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 position-code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the point to which the virtual cursor moves. The
    position-code argument is the address of a longword that contains
    the position code.

    Valid codes for position-code are as follows:

    Code               Meaning

    SMG$C_UPPER_LEFT   Row 1, column 1 (the upper left corner).
                       This is the default if position-code is not
                       specified.
    SMG$C_LOWER_LEFT   Row n, column 1 (where n is the number of
                       rows in the display). That is, the lower left
                       corner. It is useful to specify this position
                       when accepting input for an upward-scrolling
                       virtual display.
    SMG$C_UPPER_RIGHT  Row 1, column m (where m is the number of
                       columns in the display). That is, the upper
                       right corner.
    SMG$C_LOWER_RIGHT  Row n, column m (where n is the number of
                       rows and m is the number of columns in the
                       display). That is, the lower right corner.

5.60  –  SMG$INIT_TERM_TABLE

    The Initialize Terminal Table routine initializes the TERMTABLE
    database for the terminal named, so that subsequent calls to
    SMG$GET_TERM_DATA can extract information and command strings for
    that terminal.

    Format

      SMG$INIT_TERM_TABLE  terminal-name, termtable-address

5.60.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.60.2  –  Arguments

 terminal-name

    OpenVMS usage:device_name
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Specifies the name of the terminal. The terminal-name argument
    is the address of a descriptor pointing to the terminal name. The
    name must be an entry in TERMTABLE.EXE.

 termtable-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Address of the entry for a particular type of terminal in
    TERMTABLE.EXE. The termtable-address argument is the address
    of an unsigned longword that contains the address of the terminal
    capabilities table.

    You use this address when calling the SMG$GET_TERM_DATA procedure
    for the specified type of terminal. The TERMTABLE address is also
    returned by SMG$INIT_TERM_TABLE_BY_TYPE.

5.61  –  SMG$INIT_TERM_TABLE_BY_TYPE

    The Initialize TERMTABLE by OpenVMS Terminal Type routine
    initializes the TERMTABLE database for the terminal named,
    so that subsequent calls to SMG$GET_TERM_DATA can extract
    information and command strings for that terminal.

    Format

      SMG$INIT_TERM_TABLE_BY_TYPE  terminal-type ,termtable-address

                                   [,terminal-name]

5.61.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.61.2  –  Arguments

 terminal-type

    OpenVMS usage:byte_signed
    type:         byte (signed)
    access:       read only
    mechanism:    by reference

    The device type of the terminal, as designated by an OpenVMS
    symbolic terminal type or by another value returned by the
    $GETDVI system service. The terminal-type argument is the address
    of a signed byte that contains the terminal type.

 termtable-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Address of the entry for a particular type of terminal in
    TERMTABLE.EXE. The termtable-address argument is the address
    of an unsigned longword into which is written the address of a
    terminal entry.

    Use this address when calling the SMG$GET_TERM_DATA procedure for
    the specified type of terminal.

 terminal-name

    OpenVMS usage:device_name
    type:         character string
    access:       write only
    mechanism:    by descriptor

    A string into which is written the terminal name associated with
    the device type. The terminal-name argument is the address of a
    descriptor pointing to the string into which the terminal name is
    written.

5.62  –  SMG$INSERT_CHARS

    The Insert Characters routine inserts characters into a virtual
    display.

    Format

      SMG$INSERT_CHARS  display-id ,character-string ,start-row

                        ,start-column [,rendition-set]

                        [,rendition-complement] [,character-set]

5.62.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.62.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display affected. The display-id argument
    is the address of an unsigned longword that contains the display
    identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 character-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    The character string to be inserted. The character-string
    argument is the address of a descriptor that points to the string
    to be inserted.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    The row position at which to begin the insertion. The start-row
    argument is the address of a signed longword that contains the
    row number.

 start-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    The column position at which to begin the insertion. The start-
    column argument is the address of a signed longword that contains
    the column number.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to
    be complemented in the display. All of the attributes that can
    be specified with the rendition-set argument can be complemented
    with the rendition-complement argument. The display-id argument
    must be specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 character-set

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set code. Valid values are
    SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

5.63  –  SMG$INSERT_LINE

    The Insert Line routine inserts a line into a virtual display and
    scrolls the display.

    Format

      SMG$INSERT_LINE  display-id ,start-row [,character-string]

                       [,direction] [,rendition-set]

                       [,rendition-complement] [,flags]

                       [,character-set]

5.63.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.63.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display affected. The display-id argument
    is the address of an unsigned longword that contains the display
    identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the row number at which the string is inserted and at
    which scrolling begins. The start-row argument is the address of
    a signed longword that contains the row number.

 character-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    The character string to be inserted by SMG$INSERT_LINE. The
    character-string argument is the address of a descriptor pointing
    to this string.

 direction

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the scrolling direction. The direction argument is
    the address of a longword bit mask that contains the direction
    code. Valid values are SMG$M_UP and SMG$M_DOWN. SMG$M_UP is the
    default.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to
    be complemented in the display. All of the attributes that can
    be specified with the rendition-set argument can be complemented
    with the rendition-complement argument. The display-id argument
    must be specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies the action to take if the text
    does not fit on the line. The flags argument is the address of an
    unsigned longword that contains the flag. Valid values for flags
    are as follows:

    0                  Does not wrap (the default)
    SMG$M_WRAP_CHAR    Wraps at the last character on the line
    SMG$M_WRAP_WORD    Wraps at the last space on the line

 character-set

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set code. Valid values are
    SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

5.64  –  SMG$INVALIDATE_DISPLAY

    The Mark a Display as Invalid routine marks a display as invalid
    and causes the entire display to be redrawn.

    Format

      SMG$INVALIDATE_DISPLAY  display-id

5.64.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.64.2  –  Argument

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display affected. The display-id argument
    is the address of an unsigned longword that contains the display
    identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

5.65  –  SMG$KEYCODE_TO_NAME

    The Translate a Key Code into a Key Name routine translates the
    key code of a key on the keyboard into its associated key name.

    Format

      SMG$KEYCODE_TO_NAME  key-code ,key-name

5.65.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.65.2  –  Arguments

 key-code

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the key code to translate into a key name. The key-code
    argument is the address of an unsigned word that contains the key
    code.

    The key code is returned by SMG$READ_COMPOSED_LINE, SMG$READ_
    KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY in the word-
    terminator-code argument.

 key-name

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    String containing the name of the key into which key-code is
    to be translated. The key-name argument is the address of a
    descriptor pointing to the character string containing the key
    name. The key-name argument is simply the name of the key (for
    example, COMMA, PERIOD, KP4, and so forth).

5.66  –  SMG$LABEL_BORDER

    The Label a Virtual Display Border routine supplies a label for a
    virtual display's border.

    Format

      SMG$LABEL_BORDER  display-id [,text] [,position-code] [,units]

                        [,rendition-set] [,rendition-complement]

                        [,character-set]

5.66.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.66.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display affected. The display-id argument
    is the address of an unsigned longword that contains the display
    identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 text

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    The new label for this display's border. The text argument is
    the address of a descriptor pointing to the label text. If this
    string is supplied, it replaces the current label text for this
    border. If omitted, the display is not labeled.

 position-code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies which of the display's borders contains the label. The
    position-code argument is the address of an unsigned longword
    that contains the position code.

    Valid positions are as follows:

    o  SMG$K_TOP

    o  SMG$K_BOTTOM

    o  SMG$K_RIGHT

    o  SMG$K_LEFT

    If this argument is omitted, the label is displayed on the top
    border.

 units

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the character position at which the label begins
    within the border. The units argument is the address of a signed
    longword that contains the character position. If omitted, the
    label is centered in the specified border.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to
    be complemented in the display. All of the attributes that can
    be specified with the rendition-set argument can be complemented
    with the rendition-complement argument. The display-id argument
    must be specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 character-set

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set code. Valid values are
    SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

5.67  –  SMG$LIST_KEY_DEFS

    The List Key Definitions routine returns, one at a time, the
    definitions (equivalence strings) associated with specified keys
    in a specified key definition table.

    Format

      SMG$LIST_KEY_DEFS  key-table-id ,context [,key-name]

                         [,if-state] [,attributes]

                         [,equivalence-string] [,state-string]

5.67.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.67.2  –  Arguments

 key-table-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the key definition table from which you are extracting
    a key definition. The key-table-id argument is the address of an
    unsigned longword that contains the key table identifier.

    The key definition table identifier is returned by SMG$CREATE_
    KEY_TABLE.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference

    Provides a means to extract a series of key definitions from a
    key definition table. The context argument is the address of an
    unsigned longword that contains the context variable. For the
    first call to this routine, you should set the context argument
    to zero.

    The context argument is incremented by the SMG$LIST_KEY_DEFS
    routine so that the next call returns the next key definition.

 key-name

    OpenVMS usage:char_string
    type:         character string
    access:       modify
    mechanism:    by descriptor

    Identifies the key whose value you are listing. The key-name
    argument is the address of a descriptor pointing to the key name.

 if-state

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Receives the state name which qualifies the next definition in
    the key definition table. The if-state argument is the address of
    a descriptor pointing to the string into which the state name is
    written.

 attributes

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Attributes of this key definition. The attributes argument is the
    address of an unsigned longword into which the key attributes are
    written.

    Possible attributes are as follows:

    SMG$M_KEY_NOECHO   If set, this bit specifies that equiv_string
                       is not to be echoed when this key is pressed;
                       if clear, equiv_string is echoed. If SMG$M_
                       KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is
                       ignored.
    SMG$M_KEY_         If set, this bit specifies that when this key
    TERMINATE          is pressed (as qualified by if-state), the
                       input line is complete and more characters
                       should not be accepted. If clear, more
                       characters may be accepted.
    SMG$M_KEY_         If set, and if state-string is specified, the
    LOCKSTATE          state name specified by state-string remains
                       at the current state until explicitly changed
                       by a subsequent keystroke whose definition
                       includes a state-string. If clear, the state
                       name specified by state-string remains in
                       effect only for the next defined keystroke.
    SMG$M_KEY_         If set, this bit specifies that this key
    PROTECTED          definition cannot be modified or deleted.
                       If clear, the key definition can be modified
                       or deleted.

 equivalence-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    The character string into which the equivalence string is written
    for the next key definition. The equivalence-string argument is
    the address of a descriptor pointing to the string into which
    equivalence-string is written.

 state-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    A string into which is written the new state name, if any, set by
    the next key definition. The state-string argument is the address
    of a descriptor pointing to the string into which the state name
    is written. If this key definition sets a state, the attributes
    flag SMG$M_KEY_SETSTATE is also set.

5.68  –  SMG$LIST_PASTEBOARD_ORDER

    The Return Pasting Information routine returns the pasteboard
    identifier of the pasteboard to which the specified virtual
    display is pasted. Optionally, the pasteboard row 1 and column
    1 (origins) of the virtual display are also returned.

    Format

      SMG$LIST_PASTEBOARD_ORDER  display-id ,context

                                 ,pasteboard-id [,pasteboard-row]

                                 [,pasteboard-column]

5.68.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.68.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Display identifier of the virtual display that is pasted. The
    display-id argument is the address of an unsigned longword
    containing the identifier of this display.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference

    Context to search. The context argument is the address of
    an unsigned longword containing this context. On the initial
    call, you should set context to zero. SMG$LIST_PASTEBOARD_ORDER
    updates the value of context. The updated value should then be
    passed on the subsequent calls to obtain the next pasted display
    identifier.

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the identifier of the pasteboard on which the virtual
    display is pasted. The pasteboard-id argument is the address
    of an unsigned longword containing the identifier of this
    pasteboard.

 pasteboard-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Row of the pasteboard that contains row 1 of the specified
    virtual display. The optional pasteboard-row argument is the
    address of a signed longword containing the number of the
    pasteboard row that contains the first row of the virtual
    display.

 pasteboard-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Column of the pasteboard that contains column 1 of the specified
    virtual display. The optional pasteboard-column argument is
    the address of a signed longword containing the number of the
    pasteboard column that contains the first column of the virtual
    display.

5.69  –  SMG$LIST_PASTING_ORDER

    The Return Virtual Display Pasting Information routine returns
    the identifiers of the virtual displays pasted to a specified
    pasteboard. Optionally, the pasteboard row 1 and column 1
    (origins) of the virtual displays are also returned.

    Format

      SMG$LIST_PASTING_ORDER  pasteboard-id ,context ,display-id

                              [,pasteboard-row] [,pasteboard-column]

5.69.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.69.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the pasteboard on which the virtual display is
    pasted. The pasteboard-id argument is the address of an unsigned
    longword containing the identifier of this pasteboard.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference

    Context to search. The context argument is the address of an
    unsigned longword containing this context. On the initial call,
    you should set context to zero. SMG$LIST_PASTING_ORDER updates
    the value of context. The updated value should then be passed on
    subsequent calls to obtain the next pasted display identifier.

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Identifier of the virtual display that is pasted. The display-id
    argument is the address of an unsigned longword containing the
    identifier of this virtual display.

 pasteboard-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Row of the pasteboard that contains row 1 of the specified
    virtual display. The optional pasteboard-row argument is the
    address of a signed longword containing the number of the
    pasteboard row that contains the first row of the virtual
    display.

 pasteboard-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Column of the pasteboard that contains column 1 of the specified
    virtual display. The optional pasteboard-column argument is
    the address of a signed longword containing the number of the
    pasteboard column that contains the first column of the virtual
    display.

5.70  –  SMG$LOAD_KEY_DEFS

    The Load Key Definitions routine loads a file of key definitions
    (DEFINE/KEY commands) into a specified key table.

    Format

      SMG$LOAD_KEY_DEFS  key-table-id ,filespec [,default-filespec]

                         [,flags]

5.70.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.70.2  –  Arguments

 key-table-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the key table into which you are loading key
    definitions. The key-table-id argument is the address of an
    unsigned longword that contains the key table identifier.

    The key table identifier is returned by SMG$CREATE_KEY_TABLE.

 filespec

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String containing the file specification for the file of
    DEFINE/KEY commands. The filespec argument is the address of a
    descriptor pointing to the file specification.

 default-filespec

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String containing the default file specification for the file of
    DEFINE/KEY commands. The default-filespec argument is the address
    of a descriptor pointing to the default file specification. If
    omitted, the null string is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies whether filespec is to be
    treated as a logical name. The flags argument is the address
    of an unsigned longword that contains the flag. If set, flags
    specifies that filespec should be translated, but if this is not
    possible, that the null string be used.

5.71  –  SMG$LOAD_VIRTUAL_DISPLAY

    The Load a Virtual Display from a File routine creates a new
    virtual display and loads it with a virtual display saved with
    SMG$SAVE_VIRTUAL_DISPLAY.

    Format

      SMG$LOAD_VIRTUAL_DISPLAY  display-id [,filespec]

5.71.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.71.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Identifier of the new virtual display to be loaded with the
    saved virtual display. The display-id argument is the address
    of an unsigned longword into which is written the new display
    identifier.

 filespec

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String containing the file specification of the file in which the
    specified virtual display is saved. The filespec argument is a
    character string containing the file specification.

    If filespec is omitted, SMG$LOAD_VIRTUAL_DISPLAY searches for the
    default file specification SMGDISPLY.DAT.

5.72  –  SMG$MOVE_TEXT

    The Move Text from One Virtual Display to Another routine moves
    a rectangle of text from one virtual display to another virtual
    display. Given two points in opposite corners of the rectangle,
    SMG$MOVE_TEXT determines the desired width and height of the new
    virtual display.

    Format

      SMG$MOVE_TEXT  display-id ,top-left-row ,top-left-column

                     ,bottom-right-row ,bottom-right-column

                     ,display-id2 [,top-left-row2]

                     [,top-left-column2] [,flags]

5.72.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.72.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display from which text is to be moved. The
    display-id argument is the address of an unsigned longword that
    contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 top-left-row

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Top left row of the rectangle of text you want to move. The
    top-left-row argument is the address of an unsigned longword
    containing the row number.

 top-left-column

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Top left column of the rectangle of text you want to move. The
    top-left-column argument is the address of an unsigned longword
    containing the column number.

 bottom-right-row

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Bottom right row of the rectangle of text you want to move. The
    bottom-right-row argument is the address of an unsigned longword
    containing the row number.

 bottom-right-column

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Bottom right column of the rectangle of text you want to move.
    The bottom-right-column argument is the address of an unsigned
    longword containing the column number.

 display-id2

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display to which the text is to be moved.
    The display-id2 argument is the address of an unsigned longword
    that contains the display identifier.

    The display identifier display-id2 is returned by SMG$CREATE_
    VIRTUAL_DISPLAY.

 top-left-row2

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Top left row of the rectangle that is the destination of the
    text you want to move. The optional top-left-row2 argument is the
    address of an unsigned longword containing the row number. If you
    do not specify a value for top-left-row2, the text is moved to
    the current virtual cursor row.

 top-left-column2

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Top left column of the rectangle that is the destination of the
    text you want to move. The optional top-left-column2 argument is
    the address of an unsigned longword containing the column number.
    If you do not specify a value for top-left-column2, the text is
    moved to the current virtual cursor column.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies the action to take when moving
    the specified text. The flags argument is the address of an
    unsigned longword that contains the flag. The flags argument
    accepts the following values:

    SMG$M_TEXT_SAVE    Does not erase the text after moving.
    SMG$M_TEXT_ONLY    Moves the text but not the attributes.

5.73  –  SMG$MOVE_VIRTUAL_DISPLAY

    The Move Virtual Display routine relocates a virtual display on a
    pasteboard and preserves the pasting order.

    Format

      SMG$MOVE_VIRTUAL_DISPLAY  display-id ,pasteboard-id

                                ,pasteboard-row ,pasteboard-column

                                [,top-display-id]

5.73.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.73.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display to be moved. The display-id
    argument is the address of an unsigned longword that contains
    the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard on which the movement is to take place.
    The pasteboard-id argument is the address of an unsigned longword
    that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 pasteboard-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the row of the pasteboard that is to contain row
    1 of the new location of the specified virtual display. The
    pasteboard-row argument is the address of a signed longword that
    contains the row number.

 pasteboard-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column of the pasteboard that is to contain column
    1 of the specified virtual display. The pasteboard-column
    argument is the address of a signed longword that contains the
    column number.

 top-display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the virtual display under which the moving display-
    id will be pasted. The top-display-id argument is the address
    of an unsigned longword containing the specified virtual display
    identifier. Note that the use of the top-display-id argument
    is only valid when the virtual display specified by display-id
    is not currently pasted and the virtual display specified by
    top-display-id is pasted.

5.74  –  SMG$NAME_TO_KEYCODE

    The Translate a Key Name into a Key Code routine translates the
    key name of a key on the keyboard into its associated key code.

    Format

      SMG$NAME_TO_KEYCODE  key-name ,key-code

5.74.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.74.2  –  Arguments

 key-name

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String containing the name of the key to be translated into a
    key code. The key-name argument is the address of a descriptor
    pointing to the character string containing the key name. The
    key-name argument is simply the name of the key (for example,
    COMMA, PERIOD, KP4, and so forth).

 key-code

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Specifies the key code into which key-name is to be translated.
    The key-code argument is the address of an unsigned word that
    contains the key code.

    The key code is returned by SMG$READ_COMPOSED_LINE, SMG$READ_
    KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY in the word-
    terminator-code argument.

5.75  –  SMG$PASTE_VIRTUAL_DISPLAY

    The Paste Virtual Display routine pastes a virtual display to a
    pasteboard.

    Format

      SMG$PASTE_VIRTUAL_DISPLAY  display-id ,pasteboard-id

                                 [,pasteboard-row]

                                 [,pasteboard-column]

                                 [,top-display-id]

5.75.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.75.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display to be pasted. The display-id
    argument is the address of an unsigned longword that contains
    the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard to which the display is to be pasted.
    The pasteboard-id argument is the address of an unsigned longword
    that contains the pasteboard identifier.

 pasteboard-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the row of the pasteboard that is to contain row 1 of
    the specified virtual display. The pasteboard-row argument is the
    address of a signed longword that contains the row number.

    If pasteboard-row is omitted, the last row to which the virtual
    display was pasted (on any pasteboard) is used. If pasteboard-row
    is omitted and the virtual display was not previously pasted,
    then row 1 is used.

 pasteboard-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column of the pasteboard that is to contain column
    1 of the specified virtual display. The pasteboard-column
    argument is the address of a signed longword that contains the
    column number.

    If pasteboard-column is omitted, the last column to which the
    virtual display was pasted (on any pasteboard) is used. If
    pasteboard-column is omitted and the virtual display was not
    previously pasted, then column 1 is used.

 top-display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the virtual display under which to paste display-
    id. The optional top-display-id argument is the address of an
    unsigned longword containing this identifier. Note that the
    virtual display specified by top-display-id must already be
    pasted.

5.76  –  SMG$POP_VIRTUAL_DISPLAY

    The Delete a Series of Virtual Displays routine deletes a
    specified virtual display and all displays that were pasted on
    the specified pasteboard on top of the specified virtual display.

    Format

      SMG$POP_VIRTUAL_DISPLAY  display-id ,pasteboard-id

5.76.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.76.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the lowest (first) virtual display to be deleted. The
    display-id argument is the address of an unsigned longword that
    contains the display identifier. All displays that are higher in
    the pasting order (that is, all displays that were pasted after
    the specified display) are deleted as well.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard on which the display deletions take
    place. The pasteboard-id argument is the address of an unsigned
    longword that contains the pasteboard identifier.

5.77  –  SMG$PRINT_PASTEBOARD

    The Print Pasteboard Using a Print Queue routine prints the
    contents of the specified pasteboard on a line printer.

    Format

      SMG$PRINT_PASTEBOARD  pasteboard-id [,queue-name] [,copies]

                            [,form-name]

5.77.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.77.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the pasteboard to be printed. The pasteboard-id
    argument is the address of an unsigned longword containing this
    identifier.

 queue-name

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Optional queue name. The queue-name argument is the address of a
    descriptor pointing to the queue name in which to enter the file.
    The default is SYS$PRINT.

 copies

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Optional number of copies to print. The copies argument is the
    address of a signed longword containing this number. The default
    and minimum is one copy.

 form-name

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Optional name of the form to use when printing. The form-name
    argument is the address of a descriptor pointing to the form
    name. The default is "DEFAULT".

5.78  –  SMG$PUT_CHARS

    The Write Characters to a Virtual Display routine writes
    characters in a virtual display with the text you specify.

    Format

      SMG$PUT_CHARS  display-id ,text [,start-row]

                     [,start-column] [,flags] [,rendition-set]

                     [,rendition-complement] [,character-set]

5.78.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.78.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display affected. The display-id argument
    is the address of an unsigned longword that contains the display
    identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 text

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Characters to be written to the virtual display. The text
    argument is the address of a descriptor pointing to the character
    string.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the row at which output begins. If start-row is
    omitted, output begins on the current row. The start-row argument
    is the address of a signed longword that contains the row number.

 start-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column at which output begins. If start-column is
    omitted, output begins on the current column. The start-column
    argument is the address of a signed longword that contains the
    column number.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies the action to take before the
    specified text is output. The flags argument is the address of
    an unsigned longword bit mask that contains the flag. The flags
    argument accepts the following values:

    0                  Does not erase line (the default).
    SMG$M_ERASE_TO_    Erases the remaining part of the line.
    EOL
    SMG$M_ERASE_LINE   Erases the entire line.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to be
    complemented in the display. All attributes that can be specified
    with the rendition-set argument can be complemented with the
    rendition-complement argument. The display-id argument must be
    specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 character-set

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set code. Valid values are
    SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

5.79  –  SMG$PUT_CHARS_HIGHWIDE

    The Write Double-Height Double-Width Characters routine writes
    double-height, double-width (highwide) characters to a virtual
    display.

    Format

      SMG$PUT_CHARS_HIGHWIDE  display-id ,text [,start-row]

                              [,start-column] [,rendition-set]

                              [,rendition-complement]

                              [,character-set]

5.79.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.79.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display affected. The display-id argument
    is the address of an unsigned longword that contains the display
    identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 text

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Characters to be written to the virtual display. The text
    argument is the address of a descriptor pointing to the text.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the line at which output begins. The start-row argument
    is the address of a signed longword that contains the line
    number. If start-row is omitted or if it is equal to zero, output
    begins on the current line.

 start-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column at which output begins. The start-column
    argument is the address of a signed longword that contains the
    column number. If start-column is omitted or if it is equal to
    zero, output begins on the current column.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to be
    complemented in the display. All attributes that can be specified
    with the rendition-set argument can be complemented with the
    rendition-complement argument. The display-id argument must be
    specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 character-set

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set code. Valid values are
    SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

5.80  –  SMG$PUT_CHARS_MULTI

    The Put Text with Multiple Renditions to Display routine writes
    text with multiple renditions to the virtual display.

    Format

      SMG$PUT_CHARS_MULTI  display-id ,text [,start-row]

                           [,start-column] [,flags]

                           [,rendition-string]

                           [,rendition-complement] [,character-set]

5.80.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.80.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the virtual display to be affected. The display-id
    argument is the address of an unsigned longword that contains
    this identifier.

 text

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Text to be output. The text argument is the address of a
    descriptor pointing to the output string.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Optional row number at which to start output. The start-row
    argument is the address of a signed longword containing this
    number. If omitted, the current row number is used.

 start-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Optional column number at which to start output. The start-column
    argument is the address of a signed longword containing this
    number. If omitted, the current column number is used.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies the action to take before the
    specified text is output. The flags argument is the address of
    an unsigned longword that contains the flag. The flags argument
    accepts the following values:

    0                  Does not erase line (the default).
    SMG$M_ERASE_TO_    Erases the remaining part of the line.
    EOL
    SMG$M_ERASE_LINE   Erases the entire line.

 rendition-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Optional bit mask string that controls the video attributes.
    The rendition-string argument is the address of a descriptor
    pointing to the bit mask string. Each attribute set causes the
    corresponding attribute to be set for the corresponding byte in
    the text string in the display. The following attributes can be
    specified for each byte using the rendition-string argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.

 rendition-complement

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Optional bit mask string that controls the video attributes. The
    rendition-complement is the address of a descriptor pointing to
    the bit mask string. Each attribute set causes the corresponding
    attribute to be complemented for the corresponding byte in the
    text string in the display.

    If the same bit in the same byte is specified in both the
    rendition-string and rendition-complement arguments, rendition-
    string is evaluated first, followed by rendition-complement.
    By using these two parameters together, you can independently
    control each attribute in a single routine call. On a single-
    attribute basis, you can cause the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 character-set

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set code. Valid values are
    SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

5.81  –  SMG$PUT_CHARS_WIDE

    The Write Double-Width Characters routine writes double-width
    characters to a virtual display.

    Format

      SMG$PUT_CHARS_WIDE  display-id ,text [,start-row]

                          [,start-column] [,rendition-set]

                          [,rendition-complement] [,character-set]

5.81.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.81.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display affected. The display-id argument
    is the address of an unsigned longword that contains the display
    identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 text

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Characters to be written to the virtual display. The text
    argument is the address of a descriptor pointing to the text.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the line at which output begins. The start-row argument
    is the address of a signed longword that contains the line
    number. If start-row is omitted, output begins on the current
    line.

 start-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column at which output begins. If start-column is
    omitted, output begins on the current column. The start-column
    argument is the address of a signed longword that contains the
    column number.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to be
    complemented in the display. All attributes that can be specified
    with the rendition-set argument can be complemented with the
    rendition-complement argument. The display-id argument must be
    specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 character-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set code. Valid values are
    SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

5.82  –  SMG$PUT_HELP_TEXT

    The Output Help Text to the Display routine retrieves and outputs
    the help text for the specified topic in the virtual display
    provided.

    Format

      SMG$PUT_HELP_TEXT  display-id [,keyboard-id] [,help-topic]

                         [,help-library] [,rendition-set]

                         [,rendition-complement]

5.82.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.82.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Display identifier of the virtual display to which the help text
    is written. The display-id argument is the address of an unsigned
    longword that contains this virtual display identifier. Note that
    this display must be pasted and cannot be occluded or batched.

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional keyboard identifier of the virtual keyboard used for
    input. The keyboard-id argument is the address of an unsigned
    longword that contains this virtual keyboard identifier. If the
    keyboard-id parameter is not specified, prompting is disabled.

 help-topic

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Optional help topic. The help-topic argument is the address of a
    descriptor pointing to the help topic string.

 help-library

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Optional help library name. The help-library argument is the
    address of a descriptor pointing to the help library name. The
    default is SYS$HELP:HELPLIB.HLB.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to be
    complemented in the display. All attributes that can be specified
    with the rendition-set argument can be complemented with the
    rendition-complement argument. The display-id argument must be
    specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

5.83  –  SMG$PUT_LINE

    The Write Line to Virtual Display routine writes a line of text
    to a virtual display, beginning at the current virtual cursor
    position.

    Format

      SMG$PUT_LINE  display-id ,text [,line-advance] [,rendition-set]

                    [,rendition-complement] [,flags] [,character-set]

                    [,direction]

5.83.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.83.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display affected. The display-id argument
    is the address of an unsigned longword that contains the display
    identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 text

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    The characters to be written to the virtual display. The text
    argument is the address of a descriptor pointing to the text.

 line-advance

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the number of lines to advance after output. The
    line-advance argument is the address of a signed longword that
    contains the number of lines to advance. The default is 1. If you
    specify 0 for line-advance, SMG$PUT_LINE overwrites any existing
    text.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to be
    complemented in the display. All attributes that can be specified
    with the rendition-set argument can be complemented with the
    rendition-complement argument. The display-id argument must be
    specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies the action to be taken if
    the text does not fit on the line. The flags argument is the
    address of an unsigned longword that contains the flag. The flags
    argument accepts the following values:

    0                  Does not wrap (default).
    SMG$M_WRAP_CHAR    Wraps at the last character on the line.
    SMG$M_WRAP_WORD    Wraps at the last space on the line.

 character-set

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set code. Valid values are
    SMG$C_ASCII (default) and SMG$C_SPEC_GRAPHICS.

 direction

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the direction to scroll, if scrolling is necessary.
    The direction argument is the address of a longword bit mask that
    contains the direction code. Valid values are SMG$M_UP (default)
    and SMG$M_DOWN.

5.84  –  SMG$PUT_LINE_HIGHWIDE

    The Write Double-Height and Double-Width Line routine writes
    a line of text with double-height and double-width (highwide)
    characters.

    Format

      SMG$PUT_LINE_HIGHWIDE  display-id ,text [,line-advance]

                             [,rendition-set] [,rendition-complement]

                             [,flags] [,character-set]

5.84.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.84.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Display identifier. The display-id argument is the address of
    an unsigned longword that contains the display identifier of the
    virtual display.

 text

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Text to be output. The text argument is the address of the
    descriptor pointing to the output string.

 line-advance

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Number of lines to advance. The line-advance argument is the
    address of a signed longword that contains the number of lines to
    advance after the output. This argument is optional.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to be
    complemented in the display. All attributes that can be specified
    with the rendition-set argument can be complemented with the
    rendition-complement argument. The display-id argument must be
    specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies the action to be taken if
    the text does not fit on the line. The flags argument is the
    address of an unsigned longword that contains the flag. The flags
    argument accepts the following values:

    0                  Does not wrap (default).
    SMG$M_WRAP_CHAR    Wraps at the last character on the line.
    SMG$M_WRAP_WORD    Wraps at the last space on the line.

 character-set

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set code. Valid values are
    SMG$C_ASCII (default), and SMG$C_SPEC_GRAPHICS.

5.85  –  SMG$PUT_LINE_MULTI

    The Write Line with Multiple Renditions to Display routine writes
    lines with multiple renditions to the virtual display, optionally
    followed by cursor movement sequences.

    Format

      SMG$PUT_LINE_MULTI  display-id ,text ,rendition-string

                          [,rendition-complement] [,line-advance]

                          [,flags] [,direction] [,character-set]

5.85.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.85.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the virtual display to be affected. The display-id
    argument is the address of an unsigned longword that contains
    this identifier.

 text

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Text to be output. The text argument is the address of a
    descriptor pointing to the output string.

 rendition-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Optional bit mask string that controls the video attributes.
    The rendition-string argument is the address of a descriptor
    pointing to the bit mask string. Each attribute set causes the
    corresponding attribute to be set for the corresponding byte in
    the text string in the display. The following attributes can be
    specified for each byte using the rendition-string argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.

 rendition-complement

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Optional bit mask string that controls the video attributes. The
    rendition-complement is the address of a descriptor pointing to
    the bit mask string. Each attribute set causes the corresponding
    attribute to be complemented for the corresponding byte in the
    text string in the display.

    If the same bit in the same byte is specified in both the
    rendition-string and rendition-complement arguments, rendition-
    string is evaluated first, followed by rendition-complement.
    By using these two parameters together, you can independently
    control each attribute in a single routine call. On a single-
    attribute basis, you can cause the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 line-advance

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Optional number of lines to advance after output. The line-
    advance argument is the address of a signed longword containing
    this number.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies the action to take if the text
    does not fit on the line. The flags argument is the address of
    an unsigned longword that contains the flag. The flags argument
    accepts the following values:

    0                  Does not wrap (default).
    SMG$M_WRAP_CHAR    Wraps at the last character on the line.
    SMG$M_WRAP_WORD    Wraps at the last space on the line.

 direction

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional direction specifier. The direction argument is the
    address of an unsigned longword that contains the direction code
    specifying the scrolling direction, if scrolling is necessary.
    Valid values are SMG$M_UP (default) and SMG$M_DOWN.

 character-set

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set code. Valid values are
    SMG$C_ASCII (default) and SMG$C_SPEC_GRAPHICS.

5.86  –  SMG$PUT_LINE_WIDE

    The Write Double-Width Line routine writes a line of double-width
    text to a virtual display.

    Format

      SMG$PUT_LINE_WIDE  display-id ,text [,line-advance]

                         [,rendition-set] [,rendition-complement]

                         [,flags] [,character-set]

5.86.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.86.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display affected. The display-id argument
    is the address of an unsigned longword that contains the display
    identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 text

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Characters to be written to the virtual display. The text
    argument is the address of a descriptor pointing to the text.

 line-advance

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the number of lines to advance after output. The line-
    advance argument is the address of a signed longword integer that
    contains the number of lines to advance.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to be
    complemented in the display. All attributes that can be specified
    with the rendition-set argument can be complemented with the
    rendition-complement argument. The display-id argument must be
    specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies the action to take if the text
    does not fit on the line. The flags argument is the address of
    an unsigned longword that contains the flag. The flags argument
    accepts the following values:

    0                  Does not wrap (default).
    SMG$M_WRAP_CHAR    Wraps at the last character on the line.
    SMG$M_WRAP_WORD    Wraps at the last space on the line.

 character-set

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the default character set for all text in this virtual
    display. The character-set argument is the address of an unsigned
    longword that contains the character set code. Valid values are
    SMG$C_ASCII (default), and SMG$C_SPEC_GRAPHICS.

5.87  –  SMG$PUT_PASTEBOARD

    The Output Pasteboard Using Routine routine accesses the contents
    of a pasteboard.

    Format

      SMG$PUT_PASTEBOARD  pasteboard-id ,action-routine

                          [,user-argument] [,flags]

5.87.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.87.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Pasteboard identifier. The pasteboard-id argument is the address
    of an unsigned longword containing the pasteboard identifier.

 action-routine

    OpenVMS usage:procedure
    type:         procedure value
    access:       read only
    mechanism:    by value

    Pasteboard routine to be called. The action-routine argument
    is the address of the routine's procedure value. Because SMG$
    cannot determine the resulting type of device, device-independent
    characters (plus sign [+], vertical bar [|]) are used to draw
    lines.

    The action-routine accepts two arguments:

    o  A pointer to a string descriptor describing the line in the
       pasteboard.

    o  The user argument, or 0, passed by value.

    The action routine should return a success status (low bit set)
    as a return value, otherwise SMG$PUT_PASTEBOARD will terminate,
    and the status value will be returned as the return value for
    SMG$PUT_PASTEBOARD.

 user-argument

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    The argument you supply to the action-routine. The user-argument
    argument is an unsigned longword that contains the value to be
    passed to the action routine. If user-argument is omitted, a 0
    will be passed as the user argument.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies whether a form feed is passed
    to the action routine. The flags argument is the address of an
    unsigned longword that contains the flag. Valid values for flags
    are as follows:

    0                  No form-feed line is sent.
    SMG$M_FORM_FEED    The first line passed to the action routine is
                       a form feed.

5.88  –  SMG$PUT_STATUS_LINE

    The Output Line of Text to Hardware Status Line routine outputs a
    line of text to the hardware status line.

    Format

      SMG$PUT_STATUS_LINE  pasteboard-id ,text

5.88.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.88.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard containing the hardware status line.
    The pasteboard-id argument is the address of an unsigned longword
    that contains the pasteboard identifier.

 text

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    The characters to be written to the hardware status line. The
    text argument is the address of a descriptor pointing to the
    text.

5.89  –  SMG$READ_COMPOSED_LINE

    The Read Composed Line routine reads a line of input composed of
    normal keystrokes and equivalence strings.

    Format

      SMG$READ_COMPOSED_LINE  keyboard-id [,key-table-id]

                              ,resultant-string [,prompt-string]

                              [,resultant-length] [,display-id]

                              [,flags] [,initial-string]

                              [,timeout] [,rendition-set]

                              [,rendition-complement]

                              [,word-terminator-code]

5.89.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.89.2  –  Arguments

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual keyboard from which input is to be read.
    The keyboard-id argument is the address of an unsigned longword
    that contains the keyboard identifier.

    The keyboard identifier is returned by SMG$CREATE_VIRTUAL_
    KEYBOARD.

 key-table-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the key definition table to be used for translating
    keystrokes. The key-table-id argument is the address of an
    unsigned longword that contains the key definition table
    identifier.

    The key definition table identifier is returned by SMG$CREATE_
    KEY_TABLE.

 resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    String into which SMG$READ_COMPOSED_LINE writes the complete
    composed line. The resultant-string argument is the address of a
    descriptor pointing to the string in which the composed line is
    written.

 prompt-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String used to prompt for the read operation. The prompt-string
    argument is the address of a descriptor pointing to the prompt
    string.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the number of characters read or the maximum length
    of resultant-string, whichever is less. The resultant-length
    argument is the address of an unsigned longword into which
    SMG$READ_COMPOSED_LINE writes the number of characters read.

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Display identifier. The display-id argument is the address of
    an unsigned longword that contains the display identifier.
    This argument is optional only if you are not using the Screen
    Management Facility's output routines.

    If you are using the Screen Management Facility input and output
    routines, this argument specifies the virtual display in which
    the input is to occur. The virtual display specified must be
    pasted to the same pasteboard as specified by keyboard-id and
    must not be occluded. You cannot accept input from an occluded
    area of the virtual display.

    In the case of multiple virtual displays, each virtual display
    has an associated virtual cursor position. At the same time,
    there is a single physical cursor position corresponding to
    the current location of the physical cursor. If the display-id
    argument is specified, the read begins at the current virtual
    cursor position in the specified virtual display. If the display
    identifier is omitted, the read begins in the current physical
    cursor position. The length of the prompt-string plus the key
    entered is limited to the number of visible columns in the
    display.

                                   NOTE

       This virtual display must be pasted in column 1 and may
       not have any other virtual displays to its right. This
       restriction is necessary because otherwise any occurrence
       of Ctrl/R or Ctrl/U would blank out the entire line,
       including any output pasted to the right. To circumvent
       this restriction, you can use SMG$REPAINT_LINE whenever a
       Ctrl/R or Ctrl/U is encountered.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies enabled keys. The flags argument
    is the address of an unsigned longword that contains the flag.
    Valid values for flags are as follows:

    0                  Line editing is enabled and function keys (F6
                       to F14) cannot be used.
    SMG$M_FUNC_KEYS    Function keys (F6 to F14) may be used and line
                       editing is disabled.
    SMG$M_NOKEEP       Lines entered in the recall buffer are not
                       saved.
    SMG$M_NORECALL     Line recall is disabled for this I/O only.

    Because the OpenVMS terminal driver uses the function keys (F6 to
    F14) for line editing on some terminals, you cannot have function
    keys and line editing enabled at the same time.

 initial-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Optional string that contains the initial characters of the
    field. The initial-string argument is the address of a descriptor
    pointing to the string. The string is written to the display in
    the input area, as if it had been entered from the keyboard. It
    may be edited in the usual way (provided that the SMG$M_FUNC_KEYS
    flag is not set).

 timeout

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Optional timeout count. The timeout argument is the address of
    a signed longword containing the timeout count. If the timeout
    argument is specified, all characters entered before the timeout
    are returned in the buffer. If the timeout argument is omitted,
    characters are returned in the buffer until a terminator is
    encountered.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to
    be complemented in the display. All of the attributes that can
    be specified with the rendition-set argument can be complemented
    with the rendition-complement argument. The display-id argument
    must be specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 word-terminator-code

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Key terminator code. The word-terminator-code argument is an
    unsigned word into which is written a code indicating what
    character or key terminated the read. Key terminator codes are
    of the form SMG$K_TRM_keyname.

5.90  –  SMG$READ_FROM_DISPLAY

    The Read Text from Display routine reads a line of text from a
    virtual display.

    Format

      SMG$READ_FROM_DISPLAY  display-id ,resultant-string

                             [,terminator-string] [,start-row]

                             [,rendition-string]

5.90.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.90.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display from which text is read. The
    display-id argument is the address of an unsigned longword that
    contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    String into which SMG$READ_FROM_DISPLAY writes the information
    read from the virtual display. The resultant-string argument is
    the address of a descriptor pointing to the string into which the
    string is written.

 terminator-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String containing a terminator or terminators that end the
    backward search, thus determining the starting position of
    the returned string. The terminator-string argument is the
    address of a descriptor pointing to the string of terminators.
    If terminator-string is omitted, no back searching is performed;
    the returned string starts with the character at the current
    cursor position.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    The start-row argument is the address of a signed longword that
    contains the row of the virtual display to read from. This is an
    optional argument.

 rendition-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Optional bit mask string that controls the video attributes.
    The rendition-string argument is the address of a descriptor
    pointing to the bit mask string. Each attribute set causes the
    corresponding attribute to be set for the corresponding byte in
    the text string in the display. The following attributes can be
    specified for each byte using the rendition-string argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_          Specifies invisible characters; that is, the
    INVISIBLE       characters exist in the virtual display but do
                    not appear on the pasteboard.

5.91  –  SMG$READ_KEYSTROKE

    The Read a Single Character routine reads a keystroke and returns
    that keystroke's terminator code.

    Format

      SMG$READ_KEYSTROKE  keyboard-id ,word-terminator-code

                          [,prompt-string] [,timeout] [,display-id]

                          [,rendition-set] [,rendition-complement]

5.91.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.91.2  –  Arguments

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Keyboard identifier. The keyboard-id argument is an unsigned
    longword containing the identifier of the virtual keyboard from
    which to read.

    You can create a virtual keyboard by calling the SMG$CREATE_
    VIRTUAL_KEYBOARD routine.

 word-terminator-code

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Key terminator code. The word-terminator-code argument is an
    unsigned word into which is written a code indicating what
    character or key terminated the read. Key terminator codes are
    of the form SMG$K_TRM_keyname.

 prompt-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Prompt string. The prompt-string argument is an optional string
    used as the prompt for the read operation.

 timeout

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Timeout count. The timeout argument is optional. If specified,
    any character typed before the timeout is returned in the buffer.

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Display identifier. The optional display-id argument is the
    address of an unsigned longword that contains the identifier
    of the virtual display in which the read is to be performed.
    If the optional prompt-string argument is specified while there
    are multiple virtual displays pasted, the display-id argument is
    required to determine in which virtual display the prompt string
    will be written. If the prompt-string argument is not specified,
    do not specify the display-id argument.

    In the case of multiple virtual displays, each virtual display
    has an associated virtual cursor position. At the same time,
    there is a single physical cursor position corresponding to
    the current location of the physical cursor. If the display-id
    argument is specified, the read begins at the current virtual
    cursor position in the specified virtual display. If display-
    id is omitted, the read begins in the current physical cursor
    position. Note that the length of the prompt-string plus the
    key entered is limited to the number of visible columns in the
    display.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to
    be complemented in the display. All of the attributes that can
    be specified with the rendition-set argument can be complemented
    with the rendition-complement argument. The display-id argument
    must be specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

5.92  –  SMG$READ_LOCATOR

    The Read Locator Information routine reads information from a
    DECwindows workstation terminal's locator device (such as a mouse
    or tablet).

    Format

      SMG$READ_LOCATOR  keyboard-id ,row-number ,column-number

                        ,word-terminator-code [,timeout]

                        [,parse-routine]

5.92.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.92.2  –  Arguments

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Keyboard identifier. The keyboard-id argument is the address of
    an unsigned longword containing the identifier of the desired
    virtual keyboard.

    You can create a virtual keyboard by calling the SMG$CREATE_
    VIRTUAL_KEYBOARD routine.

 row-number

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Row number to which the locator is pointing. The row-number
    argument is the address of an unsigned word that contains the row
    number of the virtual display at which the locaor is pointing.

 column-number

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Column number to which the locator is pointing. The column-number
    argument is the address of an unsigned word that contains the
    column number of the virtual display at which the read is to be
    performed.

 word-terminator-code

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Locator terminator code. The word-terminator-code argument is
    the address of an unsigned word into which is written a code
    indicating what locator button terminated the read. Locator
    terminator codes are of the form SMG$K_TRM_keyname.

 timeout

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Timeout count. The optional timeout argument is the address of a
    signed longword that contains a number of seconds. If specified,
    any character typed before the timeout is returned in the buffer.

 parse-routine

    OpenVMS usage:longword_unsigned
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Address of a user-supplied parse routine that is called to parse
    the locator input. The optional parse-routine argument is the
    address of an unsigned longword that contains the parse routine.
    If this argument is not specified, ANSI locator input is assumed.

5.93  –  SMG$READ_STRING

    The Read String routine reads a string from a virtual keyboard.

    Format

      SMG$READ_STRING  keyboard-id ,resultant-string [,prompt-string]

                       [,maximum-length] [,modifiers] [,timeout]

                       [,terminator-set] [,resultant-length]

                       [,word-terminator-code] [,display-id]

                       [,initial-string] [,rendition-set]

                       [,rendition-complement] [,terminator-string]

5.93.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.93.2  –  Arguments

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual keyboard from which input is to be read.
    The keyboard-id argument is the address of an unsigned longword
    that contains the keyboard identifier.

    The keyboard identifier is returned by SMG$CREATE_VIRTUAL_
    KEYBOARD.

 resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    String into which the input line is written. The resultant-string
    argument is the address of a descriptor pointing to the string
    into which the text is written.

 prompt-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String used to prompt for the read operation. The prompt-string
    argument is the address of a descriptor pointing to the prompt
    string.

 maximum-length

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the maximum number of characters to be read. The
    maximum-length argument is the address of a signed longword that
    contains the maximum number of characters to be read. The maximum
    valid value for this argument is 512. If omitted, 512 is the
    default.

 modifiers

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies optional behavior. The modifiers
    argument is the address of an unsigned longword that contains the
    flag.

    Valid values for modifiers are as follows:

    TRM$M_TM_CVTLOW    Converts lowercase characters to uppercase
                       characters.
    TRM$M_TM_NOECHO    Characters entered are not echoed on the
                       screen.
    TRM$M_TM_NOEDIT    Advanced editing is disabled for this read
                       operation.
    TRM$M_TM_NORECALL  Line recall is disabled.
    TRM$M_TM_PURGE     Type-ahead buffer is purged before read is
                       begun.
    TRM$M_TM_          Termination character, if any, is not
    TRMNOECHO          displayed.

    The TRM$ symbols are defined by the $TRMDEF macro/module in
    system symbol libraries supplied by OpenVMS. See the terminal
    driver section of the OpenVMS I/O User's Reference Manual for
    more information on modifiers for read operations.

 timeout

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the number of seconds allowed between the time the
    prompt is issued and the completion of the input operation.
    The timeout argument is the address of a signed longword that
    contains the timeout value.

    If timeout is specified, all characters typed before the
    expiration time or until a terminate key is entered are returned
    in resultant-string. If omitted, the input operation remains
    active until a terminator is typed.

 terminator-set

    OpenVMS usage:unspecified
    type:         unspecified
    access:       read only
    mechanism:    by descriptor, fixed length

    Either a mask that specifies which characters are to be treated
    as terminators (short form) or a descriptor pointing to such a
    mask (long form). The terminator-set argument is the address of a
    descriptor pointing to the mask.

    If you want to use terminators with ASCII values in the range 0
    to 31, use the short form, which consists of two longwords. The
    first longword is zero, and the second longword is a terminator
    character bit mask. You create this mask by setting the bit that
    corresponds to the ASCII value of the desired terminator. For
    example, to specify that Ctrl/A (ASCII value 1) is a terminator,
    you set bit 1 in the terminator-set mask.

    To use terminators with ASCII values outside the range 0 to 31,
    use the long form. First create a descriptor of this form:

    31                            16 15                            0
    ----------------------------------------------------------------
    |                               |                              |
    |           (not used)          |    mask size in bytes        |
    |                               |                              |
    ----------------------------------------------------------------
    |                                                              |
    |                        address of mask                       |
    |                                                              |
    ----------------------------------------------------------------

    The mask itself has the same format as that of the short form;
    however, the long form allows the use of a more comprehensive set
    of terminator characters. For example, a mask size of 16 bytes
    allows any 7-bit ASCII character to be set as a terminator, while
    a mask size of 32 bytes allows any 8-bit character to be set as a
    terminator. Any mask size between 1 and 32 bytes is acceptable.

    If the terminator mask is all zeros, there are no specified
    terminators. In that case, the read terminates when the number
    of characters specified in maximum-length has been transferred or
    when timeout is reached.

    If the terminator-set argument is omitted, the set of terminators
    is the OpenVMS default terminator set. For more information, see
    the OpenVMS I/O User's Reference Manual.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the number of characters read or the maximum size
    of resultant-string, whichever is less. The resultant-length
    argument is the address of an unsigned word into which is written
    the number of characters read or the maximum size.

 word-terminator-code

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Key terminator code. The word-terminator-code argument is an
    unsigned word into which is written a code indicating what
    character or key terminated the read. Key terminator codes are
    of the form SMG$K_TRM_keyname.

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Display identifier. The display-id argument is the address of
    an unsigned longword that contains the display identifier.
    This argument is optional only if you are not using the Screen
    Management Facility's output routines.

    If you are using the Screen Management Facility input and output
    routines, this argument specifies the virtual display in which
    the input is to occur. The virtual display specified must be
    pasted to the same pasteboard as specified by keyboard-id and
    must not be occluded. You cannot accept input from an occluded
    area of the virtual display.

    In the case of multiple virtual displays, each virtual display
    has an associated virtual cursor position. At the same time,
    there is a single physical cursor position corresponding to
    the current location of the physical cursor. If the display-id
    argument is specified, the read begins at the current virtual
    cursor position in the specified virtual display. If display-
    id is omitted, the read begins in the current physical cursor
    position. Note that the length of the prompt-string plus the
    key entered is limited to the number of visible columns in the
    display.

                                   NOTE

       This virtual display must be pasted in column 1 and may
       not have any other virtual displays to its right. This
       restriction applies because otherwise the occurrence of a
       Ctrl/R or Ctrl/U would cause the entire line to be blanked,
       including any output to the right. To circumvent this
       restriction, you may use SMG$REPAINT_LINE to repaint the
       line when a Ctrl/R or Ctrl/U is detected.

 initial-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Initial character string. The initial-string argument is the
    address of a descriptor pointing to the optional string that
    contains the initial characters of the field. The string is
    written to the display in the input area, as if it had been
    entered from the keyboard. It may be edited in the usual
    way (provided that TRM$M_TM_NOEDIT is not set). It must be
    shorter than maximum-length, otherwise SMG$READ_STRING returns
    immediately without accepting any keyboard input.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK      Displays blinking characters.
    SMG$M_BOLD       Displays characters in higher-than-normal
                     intensity (bolded).
    SMG$M_REVERSE    Displays characters in reverse video; that is,
                     using the opposite default rendition of the
                     virtual display.
    SMG$M_UNDERLINE  Displays underlined characters.
    SMG$M_INVISIBLE  Specifies invisible characters; that is, the
                     characters exist in the virtual display but do
                     not appear on the pasteboard.
    SMG$M_USER1      Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to
    be complemented in the display. All of the attributes that can be
    specified with the rendition-set argument can be complemented
    with rendition-complement. The display-id argument must be
    specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement let
    the user control the attributes of the virtual display in which
    the read is done. The rendition-set argument sets certain virtual
    display attributes, while rendition-complement complements
    these attributes. If the same bit is specified in both the
    rendition-set and rendition-complement parameters, rendition-
    set is evaluated first, followed by rendition-complement.
    By using these two parameters together, the user can control
    each virtual display attribute in a single procedure call.
    On a single-attribute basis, the user can cause the following
    transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of current setting
    1    1          Attribute off

 terminator-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Characters that terminate I/O. The optional terminator-string
    argument is the address of a descriptor pointing to the character
    string containing the terminating characters. The terminator-
    string argument returns the actual terminating characters, not
    the key that was pressed to terminate the I/O.

5.94  –  SMG$READ_VERIFY

    The Read and Verify a String routine reads a sequence of
    characters and verifies the sequence.

    Format

      SMG$READ_VERIFY  keyboard-id ,resultant-string ,initial-string

                       ,picture-string ,fill-character

                       ,clear-character [,prompt-string]

                       [,modifiers] [,timeout] [,placeholder-arg]

                       [,initial-offset] [,word-terminator-code]

                       [,display-id] [,alternate-echo-string]

                       [,alternate-display-id] [,rendition-set]

                       [,rendition-complement] [,input-length]

5.94.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.94.2  –  Arguments

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Keyboard identifier. The keyboard-id argument is the address of
    an unsigned longword containing the identifier of the virtual
    keyboard from which to read.

    The virtual keyboard is created by calling the SMG$CREATE_
    VIRTUAL_KEYBOARD routine.

 resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Output string into which SMG$READ_VERIFY writes the characters
    that are read. The resultant-string argument is the address of a
    descriptor pointing to this output string.

 initial-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Input string that contains the initial characters of the field.
    The initial-string argument is the address of a descriptor
    pointing to the input string.

 picture-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String that contains a picture of what the field is to look
    like. The picture-string argument is the address of a descriptor
    pointing to the picture string.

    For more information on the legal values for the picture string,
    see the terminal driver section of the OpenVMS I/O User's
    Reference Manual.

 fill-character

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Fill character. The fill-character argument is the address of a
    descriptor pointing to the string that contains the character to
    be used as a fill character in the initial-string argument.

 clear-character

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Clear character. The clear-character argument is the address of
    a descriptor pointing to the string that contains the character
    to be displayed for each occurrence of fill-character in initial-
    string.

 prompt-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Prompt string. The prompt-string argument is the address of a
    descriptor pointing to the string that SMG$READ_VERIFY uses as
    the prompt for the read operation. This is an optional argument.

 modifiers

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Modifiers. The modifiers argument is a longword bit mask that
    specifies optional behavior. The bits defined are the same as
    for the $QIO item-list entry TRM$_MODIFIERS. This is an optional
    argument.

    Valid values for modifiers are as follows:

    TRM$M_TM_AUTO_TAB  Field is full when last character is entered.
    TRM$M_TM_CVTLOW    Converts lowercase characters to uppercase
                       characters.
    TRM$M_TM_NOECHO    Characters entered are not echoed on the
                       screen.
    TRM$M_TM_NOEDIT    Advanced editing is disabled for this read
                       operation.
    TRM$M_TM_NORECALL  Line recall is disabled.
    TRM$M_TM_PURGE     Type-ahead buffer is purged before read is
                       begun.
    TRM$M_TM_R_JUST    Input is right justified.
    TRM$M_TM_          Termination character, if any, is not
    TRMNOECHO          displayed.

    The TRM$ symbols are defined by the $TRMDEF macro/module in
    system symbol libraries supplied by OpenVMS. See the terminal
    driver section of the OpenVMS I/O User's Reference Manual for
    more information on modifiers for read operations.

 timeout

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Timeout count. The timeout argument is the address of a signed
    longword that contains the timeout value. The timeout argument is
    optional. If timeout is specified, all characters typed in before
    the timeout or before a terminator is entered are returned in
    the buffer. If timeout is omitted, characters are returned in the
    buffer until a terminator is seen.

 placeholder-arg

    OpenVMS usage:unspecified
    type:         unspecified
    access:       read only
    mechanism:    unspecified

    Placeholder argument. The OpenVMS terminal driver ignores this
    argument when performing a read-verify.

 initial-offset

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Input string offset. The initial-offset argument is the address
    of a signed longword that contains the number of characters (from
    the initial-string argument) to output after the prompt before
    waiting for input.

 word-terminator-code

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Key terminator code. The word-terminator-code argument is an
    unsigned word into which SMG$READ_VERIFY writes a code indicating
    what character or key terminated the read. Key terminator codes
    are of the form SMG$K_TRM_keyname.

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Display identifier. The optional display-id argument is the
    address of an unsigned longword that contains the identifier
    of the virtual display in which the read is to be performed.

    If display-id is specified, SMG$READ_VERIFY begins the read at
    the current virtual cursor position in that virtual display. If
    omitted, the read begins in the current physical cursor position.
    You cannot accept input from an occluded area of the virtual
    display.

    In the case of multiple virtual displays, each virtual display
    has an associated virtual cursor position. At the same time,
    there is a single physical cursor position corresponding to
    the current location of the physical cursor. If the display-id
    argument is specified, the read begins at the current virtual
    cursor position in the specified virtual display. If omitted,
    the read begins in the current physical cursor position. Note
    that the length of the prompt-string, the initial-offset, and the
    string entered is limited to the number of visible columns in the
    display.

 alternate-echo-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Alternate echo string. The alternate-echo-string argument is a
    string that is printed after the first character is typed during
    the read operation. This is an optional argument.

 alternate-display-id

    OpenVMS usage:identifier
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Alternate display identifier. The alternate-display-id is a
    signed longword containing the identifier of the virtual display
    in which the alternate-echo-string argument is to be printed.
    This is an optional argument. If specified, the output begins
    at the current virtual cursor position in that virtual display.
    If omitted, the value of the display-id argument is used as the
    default. If display-id is not specified, the output begins in the
    current physical cursor position.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK      Displays blinking characters.
    SMG$M_BOLD       Displays characters in higher-than-normal
                     intensity.
    SMG$M_REVERSE    Displays characters in reverse video; that is,
                     using the opposite of the default rendition of
                     the virtual display.
    SMG$M_UNDERLINE  Displays underlined characters.
    SMG$M_INVISIBLE  Specifies invisible characters; that is, the
                     characters exist in the virtual display but do
                     not appear on the pasteboard.
    SMG$M_USER1      Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to be
    complemented in the display. All attributes that can be specified
    with the rendition-set argument can be complemented with the
    rendition-complement argument. The display-id argument must be
    specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement let
    the user control the attributes of the virtual display in which
    the read is done. The rendition-set argument sets certain virtual
    display attributes, while rendition-complement complements
    these attributes. If the same bit is specified in both the
    rendition-set and rendition-complement parameters, rendition-
    set is evaluated first, followed by rendition-complement. By
    using these two parameters together, the user can control each
    virtual display attribute in a single procedure call. On a
    single-attribute basis, the user can cause the transformations
    shown in the following table.

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

 input-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of characters entered by the user. The input-length
    argument is the address of an unsigned word containing this
    number.

5.95  –  SMG$REMOVE_LINE

    The Remove a Line from a Virtual Display routine removes a
    line from a specified virtual display that was drawn with the
    SMG$DRAW_LINE or SMG$DRAW_RECTANGLE routines.

    Format

      SMG$REMOVE_LINE  display-id ,start-row ,start-column ,end-row

                       ,end-column

5.95.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.95.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display from which the line is to be
    removed. The display-id argument is the address of an unsigned
    longword that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the row at which to begin removing the line. The start-
    row argument is the address of a signed longword that contains
    the row number.

 start-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column at which to begin removing the line. The
    start-column argument is the address of a signed longword that
    contains the column number.

 end-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the row at which the line to be removed ends. The end-
    row argument is the address of a signed longword that contains
    the row number.

 end-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column at which the line to be removed ends. The
    end-column argument is the address of a signed longword that
    contains the column number.

5.96  –  SMG$REPAINT_LINE

    The Repaint One or More Lines on the Current Pasteboard routine
    repaints a series of lines on the current pasteboard.

    Format

      SMG$REPAINT_LINE  pasteboard-id ,start-row [,number-of-lines]

5.96.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.96.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Pasteboard identifier. The pasteboard-id argument is the address
    of the pasteboard associated with the physical screen to be
    repainted.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Starting row number. The start-row argument is the address of the
    pasteboard row number to start repainting.

 number-of-lines

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Number of contiguous lines to repaint. The number-of-lines
    argument is the address of a signed longword containing the
    number of lines. This argument is optional. If not specified,
    the default is 1.

5.97  –  SMG$REPAINT_SCREEN

    The Repaint Current Pasteboard routine repaints the specified
    pasteboard after non-SMG$ I/O has occurred.

    Format

      SMG$REPAINT_SCREEN  pasteboard-id

5.97.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.97.2  –  Argument

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard to be repainted. The pasteboard-id
    argument is the address of an unsigned longword that contains
    the pasteboard identifier.

5.98  –  SMG$REPASTE_VIRTUAL_DISPLAY

    The Repaste Virtual Display routine moves a virtual display
    to a new position on the pasteboard. The pasting order is not
    preserved.

    Format

      SMG$REPASTE_VIRTUAL_DISPLAY  display-id ,pasteboard-id

                                   ,pasteboard-row ,pasteboard-column

                                   [,top-display-id]

5.98.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.98.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display to be repasted. The display-id
    argument is the address of an unsigned longword that contains the
    display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard on which the display is repasted. The
    pasteboard-id argument is the address of an unsigned longword
    that contains the pasteboard identifier.

 pasteboard-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard row that is to contain row 1 of the
    specified virtual display. The pasteboard-row argument is the
    address of a signed longword that contains the pasteboard row.

 pasteboard-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard column that is to contain column 1 of
    the specified virtual display. The pasteboard-column argument
    is the address of a signed longword that contains the pasteboard
    column.

 top-display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional identifier of the virtual display under which display-
    id will be pasted. The top-display-id argument is the address of
    an unsigned longword containing the identifier of this virtual
    display. Note that the virtual display specified by top-display-
    id must already be pasted.

5.99  –  SMG$REPLACE_INPUT_LINE

    The Replace Input Line routine replaces the specified lines in
    the recall buffer with the specified string.

    Format

      SMG$REPLACE_INPUT_LINE  keyboard-id [,replace-string]

                              [,line-count] [,flags]

5.99.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.99.2  –  Arguments

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Keyboard identifier. The keyboard-id argument is the address of
    an unsigned longword containing the identifier of the virtual
    keyboard from which to read.

    You create a virtual keyboard by calling the SMG$CREATE_VIRTUAL_
    KEYBOARD routine.

 replace-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String that contains the line to be entered into the recall
    buffer. The replace-string argument is the address of a
    descriptor pointing to this string. The default is a null string,
    which removes the last line entered.

 line-count

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Number of lines to be replaced. The line-count argument is the
    address of an unsigned byte containing the number of lines to
    be replaced with replace-string. The default value for the line-
    count argument is 1 (the last line entered).

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies optional behavior. The flags argument is the address of
    an unsigned longword that contains the flag. There is one valid
    value:

    SMG$M_KEEP_CONTENTS    The string specified by replace-string
                           replaces the existing string specified by
                           line-count. By using this flag in a loop,
                           the line recall buffer can be preloaded
                           with information by the application.

5.100  –  SMG$RESTORE_PHYSICAL_SCREEN

    The Restore Physical Pasteboard routine rewrites the pasteboard
    image as it was at the time the SMG$SAVE_PHYSICAL_SCREEN routine
    was called.

    Format

      SMG$RESTORE_PHYSICAL_SCREEN  pasteboard-id ,display-id

5.100.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.100.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard to be restored. The pasteboard-id
    argument is the address of an unsigned longword that contains
    the pasteboard identifier.

    The pasteboard identifier is returned by the SMG$CREATE_
    PASTEBOARD routine.

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display created by the SMG$SAVE_PHYSICAL_
    SCREEN routine. The display-id argument is the address of an
    unsigned longword that contains this display identifier.

5.101  –  SMG$RETURN_CURSOR_POS

    The Return Cursor Position routine returns the current virtual
    cursor position in a specified virtual display.

    Format

      SMG$RETURN_CURSOR_POS  display-id ,start-row ,start-column

5.101.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.101.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display whose current virtual cursor
    position you are requesting. The display-id argument is the
    address of an unsigned longword that contains the display
    identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Receives the virtual cursor's current row position within the
    specified virtual display. The start-row argument is the address
    of a signed longword into which is written the current row
    position.

 start-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Receives the virtual cursor's current column position within
    the specified virtual display. The start-column argument is the
    address of a signed longword into which is written the current
    column position.

5.102  –  SMG$RETURN_INPUT_LINE

    The Return Input Line routine returns to the caller the requested
    line from the recall buffer. This line is retrieved either
    by matching it with a specified string or by specifying the
    appropriate line number.

    Format

      SMG$RETURN_INPUT_LINE  keyboard-id ,resultant-string

                             [,match-string]

                             [,byte-integer-line-number]

                             [,resultant-length]

5.102.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.102.2  –  Arguments

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Keyboard identifier. The keyboard-id argument is the address of
    an unsigned longword containing the identifier of the virtual
    keyboard from which to read.

    The virtual keyboard is created by calling the SMG$CREATE_
    VIRTUAL_KEYBOARD routine.

 resultant-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    String into which is written the complete recalled line. The
    resultant-string argument is the address of a descriptor pointing
    to this string.

 match-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Match string to be used when searching for the line to be
    recalled. The optional match-string argument is the address of
    a descriptor pointing to this match string. The search begins
    with the last line typed.

 byte-integer-line-number

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference

    Line number to be used when searching for the line to be
    recalled. The optional byte-integer-line-number argument is the
    address of an unsigned byte containing the number of the line to
    be recalled. The last line typed is line number 1.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Length of the resultant-string string. The optional resultant-
    length argument is the address of an unsigned word containing
    either the number of characters read or the maximum length of
    resultant-string, whichever is less.

5.103  –  SMG$RING_BELL

    The Ring the Terminal Bell or Buzzer routine sounds the terminal
    bell or buzzer.

    Format

      SMG$RING_BELL  display-id [,number-of-times]

5.103.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.103.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display for which the bell or buzzer
    sounds. The display-id argument is the address of an unsigned
    longword that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 number-of-times

    OpenVMS usage:longword_signed
    type:         longword integer (signed)
    access:       read only
    mechanism:    by reference

    Specifies the number of times the bell or buzzer is sounded.
    The number-of-times argument is the address of a signed longword
    integer that contains the number of times the bell or buzzer is
    sounded. If number-of-times is omitted, 1 is used.

5.104  –  SMG$SAVE_PHYSICAL_SCREEN

    The Save Physical Screen routine saves the contents of the
    pasteboard so that a later call to SMG$RESTORE_PHYSICAL_SCREEN
    can restore it.

    Format

      SMG$SAVE_PHYSICAL_SCREEN  pasteboard-id ,display-id

                                [,desired-start-row]

                                [,desired-end-row]

5.104.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.104.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard whose contents are to be saved. The
    pasteboard-id argument is the address of an unsigned longword
    that contains the pasteboard identifier.

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Receives the display identifier of the display created to contain
    the contents of the specified pasteboard. The display-id argument
    is the address of an unsigned longword into which the display
    identifier is written.

    The display identifier must be passed to the SMG$RESTORE_
    PHYSICAL_SCREEN routine to restore the saved information.

 desired-start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the first row to be saved. The desired-start-row
    argument is the address of a signed longword that contains
    the row number. If desired-start-row is omitted, row 1 of the
    pasteboard is used.

 desired-end-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the last row to be saved. The desired-end-row argument
    is the address of a signed longword that contains the row number.
    If desired-end-row is omitted, the last row of the pasteboard is
    used.

5.105  –  SMG$SAVE_VIRTUAL_DISPLAY

    The Save the Virtual Display to a File routine saves the contents
    of a virtual display and stores it in a file.

    Format

      SMG$SAVE_VIRTUAL_DISPLAY  display-id [,filespec]

5.105.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.105.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display to be saved. The display-id
    argument is the address of an unsigned longword that contains
    the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 filespec

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String containing the file specification of the file in which
    the specified virtual display is saved. The filespec argument
    is the address of a descriptor pointing to the character string
    containing the file specification.

    A new file is created each time this routine is called.
    If filespec is omitted, the default file specification is
    SMGDISPLY.DAT.

5.106  –  SMG$SCROLL_DISPLAY_AREA

    The Scroll Display Area routine scrolls a rectangular region of a
    virtual display.

    Format

      SMG$SCROLL_DISPLAY_AREA  display-id [,start-row]

                               [,start-column] [,height]

                               [,width] [,direction] [,count]

5.106.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.106.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display in which scrolling takes place. The
    display-id argument is the address of an unsigned longword that
    contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the first row of the scrolling region. The start-row
    argument is the address of a signed longword that contains the
    starting row.

    If start-row is omitted, row 1 of the specified virtual display
    is used.

 start-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the first column of the scrolling region. The start-
    column argument is the address of a signed longword that contains
    the starting column.

    If omitted, column 1 of the specified virtual display is used.

 height

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the number of rows in the scrolling region. The height
    argument is the address of a signed longword that contains the
    number of rows.

    If omitted, this value defaults to either the height of the
    virtual scrolling region (if one has been explicitly set with
    SMG$SET_DISPLAY_SCROLL_REGION) or the height of the specified
    virtual display.

    When scrolling a portion of a virtual display that contains
    double-height, double-width (highwide) characters, it is
    recommended that you scroll the display an even number of times.

 width

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the number of columns in the scrolling region. The
    width argument is the address of a signed longword that contains
    the number of columns.

    If omitted, this value defaults to the width of the specified
    virtual display.

 direction

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the direction to scroll. The direction argument is the
    address of a longword bit mask that contains the direction code.

    Valid values are SMG$M_UP, SMG$M_DOWN, SMG$M_RIGHT, and SMG$M_
    LEFT. SMG$M_UP is the default.

 count

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the number of lines or columns to scroll. The count
    argument is the address of a signed longword that contains the
    number of units (lines or columns) to scroll. If omitted, one
    unit is scrolled.

5.107  –  SMG$SCROLL_VIEWPORT

    The Scroll a Display Under a Viewport routine scrolls a virtual
    display under its associated viewport.

    Format

      SMG$SCROLL_VIEWPORT  display-id [,direction] [,count]

5.107.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.107.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Display identifier of the virtual display to be scrolled. The
    display-id argument is the address of an unsigned longword
    containing this identifier.

 direction

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional direction specifier. The direction argument is the
    address of a longword bit mask that contains the direction code
    specifying the scrolling direction. The optional count argument
    can be used to specify the number of lines to scroll in the
    specified direction. Valid values for direction are as follows:

    SMG$M_UP       Scroll count lines upward.
    SMG$M_DOWN     Scroll count lines downward.
    SMG$M_RIGHT    Scroll count columns to the right.
    SMG$M_LEFT     Scroll count columns to the left.

    SMG$M_UP is the default.

 count

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Optional number of rows or columns to be scrolled. The default is
    1.

5.108  –  SMG$SELECT_FROM_MENU

    The Make a Selection from the Menu routine lets you move between
    the menu choices using the arrow keys and lets you make a
    selection by pressing the Return key.

    Format

      SMG$SELECT_FROM_MENU  keyboard-id ,display-id

                            ,selected-choice-number

                            [,default-choice-number] [,flags]

                            [,help-library] [,timeout]

                            [,word-terminator-code]

                            [,selected-choice-string]

                            [,rendition-set] [,rendition-complement]

5.108.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.108.2  –  Arguments

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the virtual keyboard from which the terminal user's
    responses are read. The keyboard-id argument is the address of an
    unsigned longword containing this identifier.

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the virtual display in which the choices are
    displayed. The display-id argument is the address of an unsigned
    longword containing this display identifier. This virtual display
    must be pasted to a pasteboard and cannot be batched or occluded.

 selected-choice-number

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Identification number of the menu item selected. The selected-
    choice-number argument is the address of an unsigned word that
    receives this number. The selected-choice-number corresponds to
    the index of the menu item in the static string array specified
    in SMG$CREATE_MENU.

 default-choice-number

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Optional identification number of the default menu item. The
    default-choice-number argument is the address of an unsigned word
    that contains the number of the default menu item. The default-
    choice-number corresponds to the index of the default menu item
    in the static string array specified in SMG$CREATE_MENU. If
    omitted, the default choice will be the last menu item already
    selected, or the first item in the menu if no selections have yet
    been made.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask indicating behavior when a selection is
    made. The flags argument is the address of an unsigned longword
    containing the flag. Valid values are as follows:

    SMG$M_RETURN_     Returns control to the user when any key other
    IMMED             than an arrow key is entered.
    SMG$M_REMOVE_     Causes SMG$SELECT_FROM_MENU to allow each menu
    ITEM              item to be selected only once.

 help-library

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Optional help library to use if the PF2/Help key is pressed.
    The help-library argument is the address of a descriptor
    pointing to this help library name. Note that this argument is
    ignored if flags specifies SMG$M_RETURN_IMMED. The default is
    SYS$HELP:HELPLIB.HLB.

 timeout

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Optional timeout value. The timeout argument is the address of a
    signed longword that specifies the number of seconds to wait for
    a selection to be made.

 word-terminator-code

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Optional unsigned word that receives the code indicating which
    key terminated the read. The word-terminator-code argument is the
    address of an unsigned word that receives this terminating key
    code.

 selected-choice-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Optional string that receives the text of the menu item selected.
    The selected-choice-string is the address of a descriptor
    pointing to this string.

 rendition-set

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute specifier. The optional rendition-set argument is
    the address of a longword bit mask in which each attribute set
    causes the corresponding attribute to be set in the display. The
    following attributes can be specified using the rendition-set
    argument:

    SMG$M_BLINK     Displays blinking characters.
    SMG$M_BOLD      Displays characters in higher-than-normal
                    intensity.
    SMG$M_REVERSE   Displays characters in reverse video; that is,
                    using the opposite of the default rendition of
                    the virtual display.
    SMG$M_          Displays underlined characters.
    UNDERLINE
    SMG$M_USER1     Displays user-defined attributes.
    through
    SMG$M_USER8

    The display-id argument must be specified when you use the
    rendition-set argument.

 rendition-complement

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Attribute complement specifier. The optional rendition-
    complement argument is the address of a longword bit mask in
    which each attribute set causes the corresponding attribute to be
    complemented in the display. All attributes that can be specified
    with the rendition-set argument can be complemented with the
    rendition-complement argument. The display-id argument must be
    specified when you use the rendition-complement argument.

    The optional arguments rendition-set and rendition-complement
    let the user control the attributes of the virtual display. The
    rendition-set argument sets certain virtual display attributes,
    while rendition-complement complements these attributes. If the
    same bit is specified in both the rendition-set and rendition-
    complement parameters, rendition-set is evaluated first, followed
    by rendition-complement. By using these two parameters together,
    the user can control each virtual display attribute in a single
    procedure call. On a single-attribute basis, the user can cause
    the following transformations:

    Set  Complement Action

    0    0          Attribute set to default
    1    0          Attribute on
    0    1          Attribute set to complement of default setting
    1    1          Attribute off

5.109  –  SMG$SET_BROADCAST_TRAPPING

    The Enable Broadcast Trapping routine enables the trapping of
    broadcast messages.

    Format

      SMG$SET_BROADCAST_TRAPPING  pasteboard-id [,AST-routine]

                                  [,AST-argument]

5.109.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.109.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard for which broadcast messages are to be
    trapped. The pasteboard-id argument is the address of an unsigned
    longword that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 AST-routine

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       read only
    mechanism:    by value

    The address of an AST routine to be called when a message is
    received at the pasteboard. The AST-routine argument is the
    address of the routine's procedure value.

    When the AST-routine argument is either omitted or is given a
    value of 0, the BROADCAST mode is set to synchronize. In this
    mode, you must periodically call SMG$GET_BROADCAST_MESSAGE to see
    if any broadcast messages have arrived.

    The AST routine is called with five parameters: AST-argument, R0,
    R1, PC, and PSL (on VAX systems) or PS (on Alpha systems).

 AST-argument

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    A value to be passed to the AST routine. The AST-argument is an
    unsigned longword that contains the value to be passed to the AST
    routine.

5.110  –  SMG$SET_CURSOR_ABS

    The Set Absolute Cursor Position routine moves the virtual cursor
    to the specified position in a virtual display.

    Format

      SMG$SET_CURSOR_ABS  display-id [,start-row] [,start-column]

5.110.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.110.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display in which to set the virtual cursor
    position. The display-id argument is the address of an unsigned
    longword that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the row position to which the virtual cursor moves.
    The start-row argument is the address of a signed longword that
    contains the row number. If omitted, the cursor remains at the
    current row.

 start-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column position to which the virtual cursor moves.
    The start-column argument is the address of a signed longword
    that contains the column number. If omitted, the virtual cursor
    remains at the current column.

5.111  –  SMG$SET_CURSOR_MODE

    The Set the Cursor Mode routine turns the physical cursor on or
    off and selects jump or smooth scrolling.

    Format

      SMG$SET_CURSOR_MODE  pasteboard-id ,flags

5.111.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.111.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Pasteboard identifier. The pasteboard-id argument is the address
    of an unsigned longword that contains the pasteboard identifier.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies scrolling and cursor attributes.
    The flags argument is the address of an unsigned longword that
    contains the flag. The flags argument accepts the following
    values:

    SMG$M_CURSOR_OFF   Clears physical cursor.
    SMG$M_CURSOR_ON    Displays physical cursor.
    SMG$M_SCROLL_JUMP  Jump scrolls.
    SMG$M_SCROLL_      Smooth scrolls.
    SMOOTH

5.112  –  SMG$SET_CURSOR_REL

    The Move Cursor Relative to Current Position routine moves the
    virtual cursor the specified number of rows and columns from the
    current virtual cursor position in a virtual display.

    Format

      SMG$SET_CURSOR_REL  display-id [,delta-row] [,delta-column]

5.112.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.112.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display in which to move the virtual
    cursor. The display-id argument is the address of an unsigned
    longword that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 delta-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the number of rows to move the virtual cursor. The
    delta-row argument is the address of a signed longword that
    contains the number of rows to move. If omitted, the virtual
    cursor remains at the current row position. If delta-row is
    positive, the virtual cursor moves downward the specified number
    of rows. If delta-row is negative, the virtual cursor moves
    upward the specified number of rows.

 delta-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the number of columns to move the cursor. The delta-
    column argument is the address of a signed longword that contains
    the number of columns to move. If omitted, the virtual cursor
    remains at the current column position. If delta-column is
    positive, the virtual cursor moves the specified number of
    columns to the right. If delta-column is negative, the virtual
    cursor moves the specified number of columns to the left.

5.113  –  SMG$SET_DEFAULT_STATE

    The Set Default State routine sets and/or returns the current
    default state for a key table.

    Format

      SMG$SET_DEFAULT_STATE  key-table-id [,new-state] [,old-state]

5.113.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.113.2  –  Arguments

 key-table-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the key table in which you are setting or inquiring
    about a default state. The key-table-id argument is the address
    of an unsigned longword that contains the key table identifier.

    The key table identifier is returned by the SMG$CREATE_KEY_TABLE
    routine.

 new-state

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Specifies the new default state for the entire key table. The
    new-state argument is the address of a descriptor pointing to
    the new state string. The specified state name is converted to
    uppercase and stripped of trailing blanks before use.

 old-state

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Receives the existing default state name of the specified key
    definition table. The old-state argument is the address of a
    descriptor pointing to the string into which the old state string
    is written.

5.114  –  SMG$SET_DISPLAY_SCROLL_REGION

    The Create Display Scrolling Region routine creates a virtual
    scrolling region in a virtual display.

    Format

      SMG$SET_DISPLAY_SCROLL_REGION  display-id [,start-row]

                                     [,end-row]

5.114.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.114.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display in which scrolling takes place. The
    display-id argument is the address of an unsigned longword that
    contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 start-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the first line of the virtual scrolling region. The
    start-row argument is the address of a signed longword that
    contains the starting line number. If omitted, the first line
    of the display is used.

 end-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the last line of the virtual scrolling region. The end-
    row argument is the address of a signed longword that contains
    the ending line number. If omitted, the last line of the virtual
    display is used.

5.115  –  SMG$SET_KEYPAD_MODE

    The Set Keypad Mode routine sets the terminal's numeric keypad to
    either numeric or applications mode.

    Format

      SMG$SET_KEYPAD_MODE  keyboard-id ,flags

5.115.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.115.2  –  Arguments

 keyboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual keyboard whose mode is to be changed. The
    keyboard-id argument is the address of an unsigned longword that
    contains the keyboard identifier.

    The keyboard identifier is returned by SMG$CREATE_VIRTUAL_
    KEYBOARD.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies whether the keypad is to be in
    applications or numeric mode. The flags argument is the address
    of an unsigned longword that contains the flag. Valid values for
    flags are as follows:

    0                  Keypad is set to numeric mode.
    SMG$M_KEYPAD_      Keypad is set to applications mode.
    APPLICATION

5.116  –  SMG$SET_OUT_OF_BAND_ASTS

    The Set Out-of-Band ASTs routine either enables or disables the
    trapping of out-of-band control characters.

    Format

      SMG$SET_OUT_OF_BAND_ASTS  pasteboard-id,control-character-mask

                                ,AST-routine [,AST-argument]

5.116.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.116.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard for which out-of-band characters are
    enabled or disabled. The pasteboard-id argument is the address of
    an unsigned longword that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 control-character-mask

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies which control characters are to be the new out-of-band
    control characters. The control-character-mask argument is the
    address of an unsigned longword that contains the mask. Create
    this mask by setting the bit that corresponds to the ASCII value
    of the desired character. For example, to specify that Ctrl/C
    (ASCII value 3) is an out-of-band control character, set bit 3
    (value 8) in the control-character-mask. If no bits are set in
    this mask, then no out-of-band ASTs occur. For more information,
    see the OpenVMS I/O User's Reference Manual.

 AST-routine

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       read only
    mechanism:    by value

    The address of an AST routine to be called when an out-of-band
    control character is typed at the terminal. The AST-routine
    argument is the routine's procedure value.

 AST-argument

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    The argument you supply to the AST. AST-argument is an unsigned
    longword that contains the value to be passed to the AST routine.
    However, the AST routine may also need to determine the out-
    of-band character and the pasteboard-id at which it was typed.
    Therefore, the Screen Management Facility creates a three-
    longword structure to hold this information and passes the
    address of this structure as the first argument to the AST
    routine. The remaining four arguments are R0, R1, PC, and PSL
    (on VAX systems) or PS (on Alpha systems). The Screen Management
    Facility stores the argument you supply in this structure.

      +---------------------------+          +-------------------------+
      | address of data structure |--------->|       SMG$L_PBD_ID      |
      +---------------------------+          +-------------------------+
      |           R0              |          |      SMG$L_USER_ARG     |
      +---------------------------+          +-------------------------+
      |           R1              |          |        SMG$L_CHAR       |
      +---------------------------+          +-------------------------+
      |           PC              |
      +---------------------------+
      |          PSL              |
      +---------------------------+

    The first longword contains the pasteboard-id and has the
    symbolic name SMG$L_PBD_ID. The second longword contains the
    AST-argument and has the symbolic name SMG$L_USER_ARG. The third
    longword contains the ASCII value of the out-of-band character
    typed and can be accessed by way of two symbolic names: SMG$B_
    CHAR (the low-order byte containing the ASCII value), and SMG$L_
    CHAR (the longword containing the ASCII value in the low-order
    byte and spaces in the high-order bytes).

5.117  –  SMG$SET_PHYSICAL_CURSOR

    The Set Cursor on Physical Screen routine moves the physical
    cursor to the specified position on the pasteboard.

    Format

      SMG$SET_PHYSICAL_CURSOR  pasteboard-id ,pasteboard-row

                               ,pasteboard-column

5.117.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.117.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard whose physical cursor is to move. The
    pasteboard-id argument is the address of an unsigned longword
    that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 pasteboard-row

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the row to which the physical cursor moves. The
    pasteboard-row argument is the address of a signed longword that
    contains the row number.

 pasteboard-column

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Specifies the column to which the physical cursor moves. The
    pasteboard-column argument is the address of a signed longword
    that contains the column number.

5.118  –  SMG$SET_TERM_CHARACTERISTICS

    The Change Terminal Characteristics routine changes or retrieves
    the terminal characteristics for a given pasteboard.

    Format

      SMG$SET_TERM_CHARACTERISTICS  pasteboard-id

                                    [,on-characteristics1]

                                    [,on-characteristics2]

                                    [,off-characteristics1]

                                    [,off-characteristics2]

                                    [,old-characteristics1]

                                    [,old-characteristics2]

                                    [,on-characteristics3]

                                    [,off-characteristics3]

                                    [,old-characteristics3]

5.118.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.118.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard whose characteristics are to be changed
    or retrieved. The pasteboard-id argument is the address of an
    unsigned longword that contains the pasteboard identifier.

    The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

 on-characteristics1

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Bit mask that specifies the terminal characteristics to be set
    from $TTDEF. The on-characteristics1 argument is the address of
    an unsigned longword that contains the bit mask.

 on-characteristics2

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Bit mask that specifies the terminal characteristics to be set
    from $TT2DEF. The on-characteristics2 argument is the address of
    an unsigned longword that contains the bit mask.

 off-characteristics1

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Bit mask that specifies the terminal characteristics to be reset
    from $TTDEF. The off-characteristics1 argument is the address of
    an unsigned longword that contains the bit mask.

 off-characteristics2

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Bit mask that specifies the terminal characteristics to be reset
    from $TT2DEF. The off-characteristics2 argument is the address of
    an unsigned longword that contains the bit mask.

 old-characteristics1

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Retrieves the current terminal characteristics in the first
    group. The old-characteristics1 argument is the address of an
    unsigned longword that contains the bit mask.

 old-characteristics2

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Retrieves the current terminal characteristics in the second
    group. The old-characteristics2 argument is the address of an
    unsigned longword that contains the bit mask.

 on-characteristics3

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Bit mask that specifies the terminal characteristics to be set
    from $TT3DEF. The on-characteristics3 argument is the address of
    an unsigned longword that contains the bit mask.

 off-characteristics3

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Bit mask that specifies the terminal characteristics to be reset
    from $TT3DEF. The off-characteristics3 argument is the address of
    an unsigned longword that contains the bit mask.

 old-characteristics3

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Retrieves the current terminal characteristics in the third
    group. The old-characteristics3 argument is the address of an
    unsigned longword that contains the bit mask.

5.119  –  SMG$SNAPSHOT

    The Write Snapshot routine writes the current pasteboard buffer
    to the file or hardcopy terminal specified by the pasteboard
    identifier.

    Format

      SMG$SNAPSHOT  pasteboard-id [,flags]

5.119.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.119.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the file or hardcopy terminal to receive the contents
    of the pasteboard buffer. The pasteboard-id argument is the
    address of an unsigned longword that contains the pasteboard
    identifier. The output device associated with pasteboard-id is
    specified by the output-device argument of SMG$CREATE_PASTEBOARD.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies whether a form feed is passed.
    The flags argument is the address of an unsigned longword
    containing the flag. Valid values for flags are as follows:

    0                  No form feed is passed.
    SMG$M_FORM_FEED    The first line passed is a form feed.

5.120  –  SMG$SNAPSHOT_TO_PRINTER

    The Write Snapshot to Printer routine writes the current
    pasteboard buffer to the printer attached to the terminal.

    Format

      SMG$SNAPSHOT_TO_PRINTER  pasteboard-id ,device-type [,flags]

5.120.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.120.2  –  Arguments

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Identifier of the pasteboard whose snapshot will be sent to a
    printer. The pasteboard-id argument is the address of an unsigned
    longword that contains the pasteboard identifier.

 device-type

    OpenVMS usage:device_name
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Specifies the type of printer to which the output associated with
    this pasteboard will be written. The device-type argument is the
    address of a descriptor that points to the name of the output
    device. Valid values for this argument (for example, LA50) are
    defined in SYS$SYSTEM:TERMTABLE.TXT.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Optional bit mask that specifies whether a form feed is passed.
    The flags argument is the address of an unsigned longword
    containing the flag. The valid value for the flags argument is
    as follows:

    SMG$M_FORM_FEED    Output a form feed as the first record.

5.121  –  SMG$UNPASTE_VIRTUAL_DISPLAY

    The Remove Virtual Display routine removes a virtual display from
    a pasteboard.

    Format

      SMG$UNPASTE_VIRTUAL_DISPLAY  display-id ,pasteboard-id

5.121.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

5.121.2  –  Arguments

 display-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the virtual display to be removed from a pasteboard.
    The display-id argument is the address of an unsigned longword
    that contains the display identifier.

    The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.

 pasteboard-id

    OpenVMS usage:identifier
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Specifies the pasteboard from which the virtual display is
    removed. The pasteboard-id argument is the address of an unsigned
    longword that contains the pasteboard identifier.

6  –  STR$

6.1  –  STR$ADD

    The Add Two Decimal Strings routine adds two decimal strings of
    digits.

    Format

      STR$ADD  asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign

               ,cexp ,cdigits

6.1.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.1.2  –  Arguments

 asign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Sign of the first operand. The asign argument is the address
    of an unsigned longword containing this sign. A value of 0 is
    considered positive; a value of 1 is considered negative.

 aexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Power of 10 by which adigits is multiplied to get the absolute
    value of the first operand. The aexp argument is the address of a
    signed longword containing this exponent.

 adigits

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Text string of unsigned digits representing the absolute value of
    the first operand before aexp is applied. The adigits argument is
    the address of a descriptor pointing to this string. This string
    must be an unsigned decimal number.

 bsign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Sign of the second operand. The bsign argument is the address
    of an unsigned longword containing the second operand's sign.
    A value of 0 is considered positive; a value of 1 is considered
    negative.

 bexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Power of 10 by which bdigits is multiplied to get the absolute
    value of the second operand. The bexp argument is the address of
    a signed longword containing the second operand's exponent.

 bdigits

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Text string of unsigned digits representing the absolute value of
    the second operand before bexp is applied. The bdigits argument
    is the address of a descriptor pointing to this string. This
    string must be an unsigned decimal number.

 csign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Sign of the result. The csign argument is the address of an
    unsigned longword containing the result's sign. A value of 0
    is considered positive; a value of 1 is considered negative.

 cexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Power of 10 by which cdigits is multiplied to get the absolute
    value of the result. The cexp argument is the address of a signed
    longword containing this exponent.

 cdigits

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Text string of unsigned digits representing the absolute value
    of the result before cexp is applied. The cdigits argument is the
    address of a descriptor pointing to this string. This string is
    an unsigned decimal number.

6.2  –  STR$ANALYZE_SDESC

    The Analyze String Descriptor routine extracts the length and
    starting address of the data for a variety of string descriptor
    classes.

    Format

      STR$ANALYZE_SDESC  input-descriptor ,integer-length

                         ,data-address

6.2.1  –  Corresponding JSB Entry Point

      STR$ANALYZE_SDESC_R1

6.2.2  –  Returns

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by value

    Length of the data. The return value is the same value returned
    to the integer-length argument.

6.2.3  –  Arguments

 input-descriptor

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Input descriptor from which STR$ANALYZE_SDESC extracts the length
    of the data and the address at which the data starts. The input-
    descriptor argument is the address of a descriptor pointing to
    the input data.

 integer-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Length of the data; this length is extracted from the descriptor
    by STR$ANALYZE_SDESC. The integer-length argument is the address
    of an unsigned word integer into which STR$ANALYZE_SDESC writes
    the data length.

 data-address

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Address of the data; this address is extracted from the
    descriptor by STR$ANALYZE_SDESC. The data-address argument is an
    unsigned longword into which STR$ANALYZE_SDESC writes the address
    of the data.

6.3  –  STR$ANALYZE_SDESC_64

    (Alpha only.) The Analyze String Descriptor routine extracts the
    length and starting address of the data for a variety of string
    descriptor classes.

    Format

      STR$ANALYZE_SDESC_64  input-descriptor ,integer-length

                            ,data-address [,descriptor-type]

6.3.1  –  Corresponding JSB Entry Point

      STR$ANALYZE_SDESC_R1

                            Refer to the STR$ANALYZE_SDESC routine

                            for information about the JSB entry

                            point, STR$ANALYZE_SDESC_R1. This JSB

                            entry point returns 64-bit results on

                            Alpha systems.

6.3.2  –  Returns

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by value

    Length of the data. The return value is the same value returned
    to the integer-length argument.

6.3.3  –  Arguments

 input-descriptor

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Input descriptor from which STR$ANALYZE_SDESC_64 extracts the
    length of the data and the address at which the data starts. The
    input-descriptor argument is the address of a descriptor pointing
    to the input data. The input descriptor can be a longword
    (unsigned) or a quadword (unsigned).

 integer-length

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Length of the data; this length is extracted from the descriptor
    by STR$ANALYZE_SDESC_64. The integer-length argument is the
    address of an unsigned quadword integer into which STR$ANALYZE_
    SDESC_64 writes the data length.

 data-address

    OpenVMS usage:address
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Address of the data; this address is extracted from the
    descriptor by STR$ANALYZE_SDESC_64. The data-address argument
    is an unsigned quadword into which STR$ANALYZE_SDESC_64 writes
    the address of the data.

 descriptor-type

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Flag value indicating the type of input descriptor. The
    descriptor-type argument contains the address of an unsigned
    word integer to which STR$ANALYZE_SDESC_64 writes a zero (0) for
    a 32-bit input descriptor or a one (1) for a 64-bit descriptor.

    This argument is optional.

6.4  –  STR$APPEND

    The Append String routine appends a source string to the end of a
    destination string.

    Format

      STR$APPEND  destination-string ,source-string

6.4.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.4.2  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string to which STR$APPEND appends the source string.
    The destination-string argument is the address of a descriptor
    pointing to the destination string. This destination string
    must be dynamic or varying length. The maximum length of the
    destination string for a 32-bit descriptor is 2**16-1, or 65,535,
    bytes.

    On Alpha systems, the maximum length of the destination string
    for all 64-bit descriptor classes, except varying-length strings,
    is 2**64-1 bytes. The maximum length of a varying-length string
    is 2**16-1 for both 32-bit and 64-bit descriptors.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string that STR$APPEND appends to the end of the
    destination string. The source-string argument is the address
    of a descriptor pointing to this source string.

6.5  –  STR$CASE_BLIND_COMPARE

    The Compare Strings Without Regard to Case routine compares two
    input strings of any supported class and data type without regard
    to whether the alphabetic characters are uppercase or lowercase.

    Format

      STR$CASE_BLIND_COMPARE  first-source-string

                              ,second-source-string

6.5.1  –  Returns

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by value

    The values returned by STR$CASE_BLIND_COMPARE and the conditions
    to which they translate are as follows:

    Returned
    Value         Condition

                  first-source-string is less than second-source-
                  string.
    0             Both are the same (with blank fill for shorter
                  string).
    1             first-source-string is greater than second-source-
                  string.

6.5.2  –  Arguments

 first-source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    First string. The first-source-string argument is the address of
    a descriptor pointing to the first string.

 second-source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Second string. The second-source-string argument is the address
    of a descriptor pointing to the second string.

6.6  –  STR$COMPARE

    The Compare Two Strings routine compares the contents of two
    strings.

    Format

      STR$COMPARE  first-source-string ,second-source-string

6.6.1  –  Returns

    OpenVMS usage:longword_signed
    type:         longword integer (signed)
    access:       write only
    mechanism:    by value

    The values returned by STR$COMPARE and the conditions to which
    they translate are as follows:

    Returned
    Value         Condition

                  first-source-string is less than second-source-
                  string.
    0             first-source-string is equal to second-source-
                  string.
    1             first-source-string is greater than second-source-
                  string.

6.6.2  –  Arguments

 first-source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    First string. The first-source-string argument is the address of
    a descriptor pointing to the first string.

 second-source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Second string. The second-source-string argument is the address
    of a descriptor pointing to the second string.

6.7  –  STR$COMPARE_EQL

    The Compare Two Strings for Equality routine compares two strings
    to see if they have the same length and contents. Uppercase and
    lowercase characters are not considered equal.

    Format

      STR$COMPARE_EQL  first-source-string ,second-source-string

6.7.1  –  Returns

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    The values returned by STR$COMPARE and the conditions to which
    they translate are as follows:

    Returned
    Value         Condition

    0             The length and the contents of first-source-string
                  are equal to the length and contents of second-
                  source-string.
    1             Either the length of first-source-string is not
                  equal to the length of second-source-string, or the
                  contents of first-source-string are not equal to
                  the contents of second-source-string, or both.

6.7.2  –  Arguments

 first-source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    First source string. The first-source-string argument is the
    address of a descriptor pointing to the first source string.

 second-source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Second source string. The second-source-string argument is the
    address of a descriptor pointing to the second source string.

6.8  –  STR$COMPARE_MULTI

    The Compare Two Strings for Equality Using Multinational
    Character Set routine compares two character strings for equality
    using the DEC Multinational Character Set.

    Format

      STR$COMPARE_MULTI  first-source-string ,second-source-string

                         [,flags-value] [,foreign-language]

6.8.1  –  Returns

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by value

    The values returned by STR$COMPARE_MULTI and the conditions to
    which they translate are as follows:

    Returned
    Value         Condition

                  first-source-string is less than second-source-
                  string.
    0             Both strings are the same; the shorter string is
                  blank filled.
    1             first-source-string is greater than second-source-
                  string.

6.8.2  –  Arguments

 first-source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    First string in the comparison. The first-source-string argument
    is the address of a descriptor pointing to the first string.

 second-source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Second string in the comparison. The second-source-string
    argument is the address of a descriptor pointing to the second
    string.

 flags-value

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    A single flag bit. The flags-value argument is a signed longword
    integer that contains this flag bit. The flags-value argument
    indicates whether the comparison is to be case sensitive or case
    blind. The default value of flags-value is 0, indicating a case
    sensitive comparison. The following table lists the meaning of
    the bit values:

    Value Meaning

    0     Uppercase and lowercase characters are not equivalent. (The
          comparison is case sensitive.)
    1     Uppercase and lowercase characters are equivalent. (The
          comparison is case blind.)

 foreign-language

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value

    Indicator that determines the foreign language table to be
    used. The foreign-language argument is an unsigned longword that
    contains this foreign language table indicator. The default value
    of foreign-language is 1. The following table lists the value
    of the foreign-language argument associated with each language
    table:

    Value Language

    1     Multinational table
    2     Danish table
    3     Finnish/Swedish table
    4     German table
    5     Norwegian table
    6     Spanish table

6.9  –  STR$CONCAT

    The Concatenate Two or More Strings routine concatenates all
    specified source strings into a single destination string.

    Format

      STR$CONCAT  destination-string ,source-string

                  [,source-string...]

6.9.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.9.2  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$CONCAT concatenates all
    specified source strings. The destination-string argument is
    the address of a descriptor pointing to this destination string.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    First source string; STR$CONCAT requires at least one source
    string. The source-string argument is the address of a descriptor
    pointing to the first source string. The maximum number of source
    strings that STR$CONCAT allows is 254.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Additional source strings; STR$CONCAT requires at least one
    source string. The source-string argument is the address of a
    descriptor pointing to the additional source string. The maximum
    number of source strings that STR$CONCAT allows is 254.

6.10  –  STR$COPY_DX

    The Copy a Source String Passed by Descriptor to a Destination
    String routine copies a source string to a destination string.
    Both strings are passed by descriptor.

    Format

      STR$COPY_DX  destination-string ,source-string

6.10.1  –  Corresponding JSB Entry Point

      STR$COPY_DX_R8

6.10.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.10.3  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$COPY_DX writes the source
    string. Depending on the class of the destination string, the
    following actions occur:

    Descriptor
    Class          Action

    S, Z, SD, A,   Copy the source string. If needed, fill space or
    NCA            truncate on the right.
    D              If the area specified by the destination
                   descriptor is large enough to contain the source
                   string, copy the source string and set the new
                   length in the destination descriptor. If the area
                   specified is not large enough, return the previous
                   space allocation (if any) and then dynamically
                   allocate the amount of space needed. Copy the
                   source string and set the new length and address
                   in the destination descriptor.
    VS             Copy the source string to the destination string
                   up to the limit of the descriptor's MAXSTRLEN
                   field with no padding. Adjust the string's current
                   length (CURLEN) field to the actual number of
                   bytes copied.

    The destination-string argument is the address of a descriptor
    pointing to the destination string.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string that STR$COPY_DX copies into the destination
    string; the descriptor class of the source string can be
    unspecified, fixed length, dynamic length, scalar decimal,
    array, noncontiguous array, or varying length. The source-string
    argument is the address of a descriptor pointing to this source
    string. (See the description of LIB$ANALYZE_SDESC for possible
    restrictions.)

6.11  –  STR$COPY_R

    The Copy a Source String Passed by Reference to a Destination
    String routine copies a source string passed by reference to a
    destination string passed by descriptor.

    Format

      STR$COPY_R  destination-string ,word-integer-source-length

                  ,source-string-address

6.11.1  –  Corresponding JSB Entry Point

      STR$COPY_R_R8

6.11.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.11.3  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$COPY_R copies the source
    string. The destination-string argument is the address of a
    descriptor pointing to the destination string.

    The class field determines the appropriate action.

    See the description of LIB$ANALYZE_SDESC for restrictions
    associated with specific descriptor classes.

 word-integer-source-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Length of the source string. The word-integer-source-length
    argument is the address of an unsigned word containing the length
    of the source string.

 source-string-address

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by reference

    Source string that STR$COPY_R copies into the destination string.
    The source-string-address argument is the address of the source
    string.

6.12  –  STR$COPY_R_64

    (Alpha only.) The Copy a Source String Passed by Reference to
    a Destination String routine copies a source string passed by
    reference to a destination string passed by descriptor.

    Format

      STR$COPY_R_64  destination-string ,quad-integer-source-length

                     ,source-string-address

6.12.1  –  Corresponding JSB Entry Point

      STR$COPY_R_R8

6.12.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.12.3  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$COPY_R_64 copies the source
    string. The destination-string argument is the address of a
    descriptor pointing to the destination string.

    The class field determines the appropriate action.

    See the description of LIB$ANALYZE_SDESC for restrictions
    associated with specific descriptor classes.

 quad-integer-source-length

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Length of the source string. The quad-integer-source-length
    argument is the address of an unsigned quadword containing the
    length of the source string.

 source-string-address

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by reference

    Source string that STR$COPY_R_64 copies into the destination
    string. The source-string-address argument is the address of the
    source string.

6.13  –  STR$DIVIDE

    The Divide Two Decimal Strings routine divides two decimal
    strings.

    Format

      STR$DIVIDE  asign ,aexp ,adigits ,bsign ,bexp ,bdigits

                  ,total-digits ,round-truncate-indicator ,csign

                  ,cexp ,cdigits

6.13.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.13.2  –  Arguments

 asign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Sign of the first operand. The asign argument is the address of
    an unsigned longword containing the sign of the first operand.
    A value of 0 is considered positive; a value of 1 is considered
    negative.

 aexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Power of 10 by which adigits is multiplied to get the absolute
    value of the first operand. The aexp argument is the address of
    the first operand's exponent.

 adigits

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    First operand's numeric text string. The adigits argument is the
    address of a descriptor pointing to the first operand's numeric
    string. The string must be an unsigned decimal number.

 bsign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Sign of the second operand. The bsign argument is the address
    of an unsigned longword containing the second operand's string.
    A value of 0 is considered positive; a value of 1 is considered
    negative.

 bexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Power of 10 by which bdigits is multiplied to get the absolute
    value of the second operand. The bexp argument is the address of
    the second operand's exponent.

 bdigits

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Second operand's numeric text string. The bdigits argument is the
    address of a descriptor pointing to the second operand's number
    string. The string must be an unsigned decimal number.

 total-digits

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Number of digits to the right of the decimal point. The total-
    digits argument is the address of a signed longword containing
    the number of total digits. STR$DIVIDE uses this number to carry
    out the division.

 round-truncate-indicator

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Indicator of whether STR$DIVIDE is to round or truncate the
    result; a value of 0 means truncate; a value of 1 means round.
    The round-truncate-indicator argument is the address of a
    longword bit mask containing this indicator.

 csign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Sign of the result. The csign argument is the address of an
    unsigned longword containing the sign of the result. A value
    of 0 is considered positive; a value of 1 is considered negative.

 cexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Power of 10 by which cdigits is multiplied to get the absolute
    value of the result. The cexp argument is the address of a signed
    longword containing the exponent.

 cdigits

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Result's numeric text string. The cdigits argument is the address
    of a descriptor pointing to the numeric string of the result.
    This string is an unsigned decimal number.

6.14  –  STR$DUPL_CHAR

    The Duplicate Character n Times routine generates a string
    containing n duplicates of the input character. If the
    destination string is an "empty" dynamic-length string
    descriptor, STR$DUPL_CHAR allocates and initializes the string.

    Format

      STR$DUPL_CHAR  destination-string [,repetition-count]

                     [,ASCII-character]

6.14.1  –  Corresponding JSB Entry Point

      STR$DUPL_CHAR_R8

6.14.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.14.3  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$DUPL_CHAR writes repetition-
    count copies of the input character. The destination-string
    argument is the address of a descriptor pointing to the
    destination string. The maximum length of the destination string
    for a 32-bit descriptor is 2**16-1, or 65,535, bytes.

    On Alpha systems, the maximum length of the destination string
    for all 64-bit descriptor classes, except varying strings, is
    2**64-1 bytes. The maximum length of a varying-length string is
    2**16-1 for both 32-bit and 64-bit descriptors.

 repetition-count

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Number of times ASCII-character is duplicated; this is an
    optional argument (if omitted, the default is 1). The repetition-
    count argument is the address of a signed longword containing the
    number.

 ASCII-character

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by reference

    ASCII character that STR$DUPL_CHAR writes repetition-count times
    into the destination string. The ASCII-character argument is the
    address of a character string containing this character. This is
    an optional argument; if omitted, the default is a space.

6.15  –  STR$ELEMENT

    The Extract Delimited Element Substring routine extracts an
    element from a string in which the elements are separated by a
    specified delimiter.

    Format

      STR$ELEMENT  destination-string ,element-number

                   ,delimiter-string ,source-string

6.15.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.15.2  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$ELEMENT copies the selected
    substring. The destination-string argument is the address of a
    descriptor pointing to the destination string.

 element-number

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Element number of the delimited element substring to be returned.
    The element-number argument is the address of a signed longword
    containing the desired element number. Zero is used to represent
    the first delimited element substring, one is used to represent
    the second, and so forth.

 delimiter-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Delimiter string used to separate element substrings. The
    delimiter-string argument is the address of a descriptor pointing
    to the delimiter string. The delimiter-string argument must be
    exactly one character long.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string from which STR$ELEMENT extracts the requested
    delimited substring. The source-string argument is the address
    of a descriptor pointing to the source string.

6.16  –  STR$FIND_FIRST_IN_SET

    The Find First Character in a Set of Characters routine searches
    a string, comparing each character to the characters in a
    specified set of characters. The string is searched character
    by character, from left to right. STR$FIND_FIRST_IN_SET returns
    the position of the first character in the string that matches
    any of the characters in the selected set of characters.

    Format

      STR$FIND_FIRST_IN_SET  source-string ,set-of-characters

6.16.1  –  Returns

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by value

    Position in source-string where the first match is found; zero if
    no match is found.

    On Alpha systems, if the relative position of the substring can
    exceed 2**32-1, assign the return value to a quadword to ensure
    that you retrieve the correct relative position.

6.16.2  –  Arguments

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String that STR$FIND_FIRST_IN_SET compares to the set of
    characters, looking for the first match. The source-string
    argument is the address of a descriptor pointing to the character
    string.

 set-of-characters

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Set of characters that STR$FIND_FIRST_IN_SET is searching for
    in the string. The source-string argument is the address of a
    descriptor pointing to the set of characters.

6.17  –  STR$FIND_FIRST_NOT_IN_SET

    The Find First Character That Does Not Occur in Set routine
    searches a string, comparing each character to the characters in
    a specified set of characters. The string is searched character
    by character, from left to right. STR$FIND_FIRST_NOT_IN_SET
    returns the position of the first character in the string that
    does not match any of the characters in the selected set of
    characters.

    Format

      STR$FIND_FIRST_NOT_IN_SET  source-string ,set-of-characters

6.17.1  –  Returns

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by value

    Position in source-string where a nonmatch was found.

    On Alpha systems, if the relative position of the substring can
    exceed 2**32-1, assign the return value to a quadword to ensure
    that you retrieve the correct relative position.

    Returned
    Value         Condition

    0             Either all characters in source-string match some
                  characters in set-of-characters, or there were no
                  characters in set-of-characters.
    1             Either the first nonmatching character in source-
                  string was found in position 1, or there were no
                  characters in source-string.
    N             The first nonmatching character was found in
                  position N within source-string.

6.17.2  –  Arguments

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String that STR$FIND_FIRST_NOT_IN_SET searches. The source-string
    argument is the address of a descriptor pointing to the string.

 set-of-characters

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    The set of characters that STR$FIND_FIRST_NOT_IN_SET compares
    to the string, looking for a nonmatch. The set-of-characters
    argument is the address of a descriptor pointing to this set of
    characters.

6.18  –  STR$FIND_FIRST_SUBSTRING

    The Find First Substring in Input String routine finds the first
    substring (in a provided list of substrings) occurring in a given
    string.

    Format

      STR$FIND_FIRST_SUBSTRING  source-string ,index ,substring-index

                                ,substring [,substring...]

6.18.1  –  Returns

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    The values returned by STR$FIND_FIRST_SUBSTRING and the
    conditions to which they translate are as follows:

    Returned
    Value          Condition

    0              source-string did not contain any of the specified
                   substrings.
    1              STR$FIND_FIRST_SUBSTRING found at least one of the
                   specified substrings in source-string.

6.18.2  –  Arguments

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String that STR$FIND_FIRST_SUBSTRING searches. The source-string
    argument is the address of a descriptor pointing to the string.

 index

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Earliest position within source-string at which STR$FIND_FIRST_
    SUBSTRING found a matching substring; zero if no matching
    substring was found. The index argument is the address of a
    signed longword containing this position.

 substring-index

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Ordinal number of the substring that matched (1 for the first, 2
    for the second, and so on), or zero if STR$FIND_FIRST_SUBSTRING
    found no substrings that matched. The substring-index argument is
    the address of a signed longword containing this ordinal number.

 substring

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Specified substring for which STR$FIND_FIRST_SUBSTRING searches
    in source-string. The substring argument is the address of a
    descriptor pointing to the first substring. You can specify
    multiple substrings to search for.

 substring

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Additional specified substring for which STR$FIND_FIRST_SUBSTRING
    searches in source-string. The substring argument is the address
    of a descriptor pointing to the substring. You can specify
    multiple substrings to search for.

6.19  –  STR$FREE1_DX

    The Free One Dynamic String routine deallocates one dynamic
    string.

    Format

      STR$FREE1_DX  string-descriptor

6.19.1  –  Corresponding JSB Entry Point

      STR$FREE1_DX_R4

6.19.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.19.3  –  Argument

 string-descriptor

    OpenVMS usage:char_string
    type:         character string
    access:       modify
    mechanism:    by descriptor

    Dynamic string descriptor of the dynamic string that STR$FREE1_
    DX deallocates. The string-descriptor argument is the address
    of a descriptor pointing to the string to be deallocated. The
    descriptor's CLASS field is checked.

6.20  –  STR$GET1_DX

    The Allocate One Dynamic String routine allocates a specified
    number of bytes of virtual memory to a specified dynamic string
    descriptor.

    Format

      STR$GET1_DX  word-integer-length ,character-string

6.20.1  –  Corresponding JSB Entry Point

      STR$GET1_DX_R4

6.20.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.20.3  –  Arguments

 word-integer-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference

    Number of bytes that STR$GET1_DX allocates. The word-integer-
    length argument is the address of an unsigned word containing
    this number.

 character-string

    OpenVMS usage:char_string
    type:         character string
    access:       modify
    mechanism:    by descriptor

    Dynamic string descriptor to which STR$GET1_DX allocates the
    area. The character-string argument is the address of the
    descriptor. The descriptor's CLASS field is checked.

6.21  –  STR$GET1_DX_64

    (Alpha only.) The Allocate One Dynamic String routine allocates
    a specified number of bytes of virtual memory to a specified
    dynamic string descriptor.

    Format

      STR$GET1_DX_64  quad-integer-length ,character-string

6.21.1  –  Corresponding JSB Entry Point

      STR$GET1_DX_R4

6.21.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.21.3  –  Arguments

 quad-integer-length

    OpenVMS usage:quadword_unsigned
    type:         quadword (unsigned)
    access:       read only
    mechanism:    by reference

    Number of bytes that STR$GET1_DX_64 allocates. The quad-integer-
    length argument is the address of an unsigned quadword containing
    this number.

 character-string

    OpenVMS usage:char_string
    type:         character string
    access:       modify
    mechanism:    by descriptor

    Dynamic string descriptor to which STR$GET1_DX_64 allocates
    the area. The character-string argument is the address of the
    descriptor. The descriptor's CLASS field is checked.

6.22  –  STR$LEFT

    The Extract a Substring of a String routine copies a substring
    beginning at the first character of a source string into a
    destination string.

    Format

      STR$LEFT  destination-string ,source-string ,end-position

6.22.1  –  Corresponding JSB Entry Point

      STR$LEFT_R8

6.22.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.22.3  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$LEFT copies the substring.
    The destination-string argument is the address of a descriptor
    pointing to the destination string.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string from which STR$LEFT extracts the substring that it
    copies into the destination string. The source-string argument is
    the address of a descriptor pointing to the source string.

 end-position

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Relative position in the source string at which the substring
    ends. The end-position argument is the address of a signed
    longword containing the ending position.

    STR$LEFT copies all characters in the source string from position
    1 (the leftmost position) to the position number specified in
    this end-position argument.

6.23  –  STR$LEN_EXTR

    The Extract a Substring of a String routine copies a substring of
    a source string into a destination string.

    Format

      STR$LEN_EXTR  destination-string ,source-string ,start-position

                    ,longword-integer-length

6.23.1  –  Corresponding JSB Entry Point

      STR$LEN_EXTR_R8

6.23.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.23.3  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$LEN_EXTR copies the substring.
    The destination-string argument is the address of a descriptor
    pointing to the destination string.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string from which STR$LEN_EXTR extracts the substring that
    it copies into the destination string. The source-string argument
    is the address of a descriptor pointing to the source string.

 start-position

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Relative position in the source string at which STR$LEN_EXTR
    begins copying the substring. The start-position argument is the
    address of a signed longword containing the starting position.

 longword-integer-length

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Number of characters in the substring that STR$LEN_EXTR copies
    to the destination string. The longword-integer-length argument
    is the address of a signed longword containing the length of the
    substring.

6.24  –  STR$MATCH_WILD

    The Match Wildcard Specification routine compares a pattern
    string that includes wildcard characters with a candidate string.

    Format

      STR$MATCH_WILD  candidate-string ,pattern-string

6.24.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Returns a condition value of STR$_MATCH if the strings match and
    STR$_NOMATCH if they do not match.

6.24.2  –  Arguments

 candidate-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String that is compared to the pattern string. The candidate-
    string argument is the address of a descriptor pointing to the
    candidate string.

 pattern-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    String containing wildcard characters. The pattern-string
    argument is the address of a descriptor pointing to the pattern
    string. The wildcards in the pattern string are translated when
    STR$MATCH_WILD searches the candidate string to determine if it
    matches the pattern string.

6.25  –  STR$MUL

    The Multiply Two Decimal Strings routine multiplies two decimal
    strings.

    Format

      STR$MUL  asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign

               ,cexp ,cdigits

6.25.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.25.2  –  Arguments

 asign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Sign of the first operand. The asign argument is the address of
    an unsigned longword containing the first operand's sign. A value
    of 0 is considered positive; a value of 1 is considered negative.

 aexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Power of 10 by which adigits is multiplied to get the absolute
    value of the first operand. The aexp argument is the address of a
    signed longword containing this exponent.

 adigits

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    First operand's numeric text string. The adigits argument is the
    address of a descriptor pointing to the numeric string of the
    first operand. The string must be an unsigned decimal number.

 bsign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Sign of the second operand. The bsign argument is the address of
    an unsigned longword containing the sign of the second operand.
    A value of 0 is considered positive; a value of 1 is considered
    negative.

 bexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Power of 10 by which bdigits is multiplied to get the absolute
    value of the second operand. The bexp argument is the address of
    a signed longword containing this exponent.

 bdigits

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Second operand's numeric text string. The bdigits argument is the
    address of a descriptor pointing to the second operand's numeric
    string. The string must be an unsigned decimal number.

 csign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Sign of the result. The csign argument is the address of an
    unsigned longword containing the sign of the result. A value
    of 0 is considered positive; a value of 1 is considered negative.

 cexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Power of 10 by which cdigits is multiplied to get the absolute
    value of the result. The cexp argument is the address of a signed
    longword containing this exponent.

 cdigits

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Result's numeric text string. The cdigits argument is the address
    of a descriptor pointing to the numeric string of the result. The
    string is an unsigned decimal number.

6.26  –  STR$POSITION

    The Return Relative Position of Substring routine searches for
    the first occurrence of a single substring within a source
    string. If STR$POSITION finds the substring, it returns the
    relative position of that substring. If the substring is not
    found, STR$POSITION returns a zero.

    Format

      STR$POSITION  source-string ,substring [,start-position]

6.26.1  –  Corresponding JSB Entry Point

      STR$POSITION_R6

6.26.2  –  Returns

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Relative position of the first character of the substring. Zero
    is the value returned if STR$POSITION did not find the substring.

    On Alpha systems, if the relative position of the substring can
    exceed 2**32-1, assign the return value to a quadword to ensure
    that you retrieve the correct relative position.

6.26.3  –  Arguments

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string within which STR$POSITION searches for the
    substring. The source-string argument is the address of a
    descriptor pointing to the source string.

 substring

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Substring for which STR$POSITION searches. The substring argument
    is the address of a descriptor pointing to the substring.

 start-position

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Relative position in the source string at which STR$POSITION
    begins the search. The start-position argument is the address of
    a signed longword containing the starting position. Although this
    is an optional argument, it is required if you are using the JSB
    entry point.

    If start-position is not supplied, STR$POSITION starts the search
    at the first character position of source-string.

6.27  –  STR$POS_EXTR

    The Extract a Substring of a String routine copies a substring of
    a source string into a destination string.

    Format

      STR$POS_EXTR  destination-string ,source-string ,start-position

                    ,end-position

6.27.1  –  Corresponding JSB Entry Point

      STR$POS_EXTR_R8

6.27.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.27.3  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$POS_EXTR copies the substring.
    The destination-string argument is the address of a descriptor
    pointing to the destination string.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string from which STR$POS_EXTR extracts the substring that
    it copies into the destination string. The source-string argument
    is the address of a descriptor pointing to the source string.

 start-position

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Relative position in the source string at which STR$POS_EXTR
    begins copying the substring. The start-position argument is the
    address of a signed longword containing the starting position.

 end-position

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Relative position in the source string at which STR$POS_EXTR
    stops copying the substring. The end-position argument is the
    address of a signed longword containing the ending position.

6.28  –  STR$PREFIX

    The Prefix a String routine inserts a source string at the
    beginning of a destination string. The destination string must
    be dynamic or varying length.

    Format

      STR$PREFIX  destination-string ,source-string

6.28.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.28.2  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string (dynamic or varying length). STR$PREFIX copies
    the source string into the beginning of this destination string.
    The destination-string argument is the address of a descriptor
    pointing to the destination string.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string that STR$PREFIX copies into the beginning of the
    destination string. The source-string argument is the address of
    a descriptor pointing to the source string.

6.29  –  STR$RECIP

    The Reciprocal of a Decimal String routine takes the reciprocal
    of the first decimal string to the precision limit specified by
    the second decimal string and returns the result as a decimal
    string.

    Format

      STR$RECIP  asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign

                 ,cexp ,cdigits

6.29.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.29.2  –  Arguments

 asign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Sign of the first operand. The asign argument is the address of
    an unsigned longword containing the first operand's sign. A value
    of 0 is considered positive; a value of 1 is considered negative.

 aexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Power of 10 by which adigits is multiplied to get the absolute
    value of the first operand. The aexp argument is the address of a
    signed longword containing this exponent.

 adigits

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    First operand's numeric text string. The adigits argument is the
    address of a descriptor pointing to the first operand's numeric
    string. The string must be an unsigned decimal number.

 bsign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Sign of the second operand. The bsign argument is the address of
    an unsigned longword containing the sign of the second operand.
    A value of 0 is considered positive; a value of 1 is considered
    negative.

 bexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Power of 10 by which bdigits is multiplied to get the absolute
    value of the second operand. The bexp argument is the address of
    a signed longword containing this exponent.

 bdigits

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Second operand's numeric text string. The bdigits argument is the
    address of a descriptor pointing to the second operand's numeric
    string. The string must be an unsigned decimal number.

 csign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Sign of the result. The csign argument is the address of an
    unsigned longword containing the result's sign. A value of 0
    is considered positive; a value of 1 is considered negative.

 cexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Power of 10 by which cdigits is multiplied to get the absolute
    value of the result. The cexp argument is the address of a signed
    longword containing this exponent.

 cdigits

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Result's numeric text string. The cdigits argument is the address
    of a descriptor pointing to the result's numeric string. The
    string is an unsigned decimal number.

6.30  –  STR$REPLACE

    The Replace a Substring routine copies a source string to a
    destination string, replacing part of the string with another
    string. The substring to be replaced is specified by its starting
    and ending positions.

    Format

      STR$REPLACE  destination-string ,source-string ,start-position

                   ,end-position ,replacement-string

6.30.1  –  Corresponding JSB Entry Point

      STR$REPLACE_R8

6.30.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.30.3  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$REPLACE writes the new string
    created when it replaces the substring. The destination-
    string argument is the address of a descriptor pointing to the
    destination string.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string. The source-string argument is the address of a
    descriptor pointing to the source string.

 start-position

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Position in the source string at which the substring that
    STR$REPLACE replaces begins. The start-position argument is the
    address of a signed longword containing the starting position.
    The position is relative to the start of the source string.

 end-position

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Position in the source string at which the substring that
    STR$REPLACE replaces ends. The end-position argument is the
    address of a signed longword containing the ending position.
    The position is relative to the start of the source string.

 replacement-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Replacement string with which STR$REPLACE replaces the substring.
    The replacement-string argument is the address of a descriptor
    pointing to this replacement string. The value of replacement-
    string must be equal to end-position minus start-position.

6.31  –  STR$RIGHT

    The Extract a Substring of a String routine copies a substring
    ending at the last character of a source string into a
    destination string.

    Format

      STR$RIGHT  destination-string ,source-string ,start-position

6.31.1  –  Corresponding JSB Entry Point

      STR$RIGHT_R8

6.31.2  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.31.3  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$RIGHT copies the substring.
    The destination-string argument is the address of a descriptor
    pointing to the destination string.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string from which STR$RIGHT extracts the substring that it
    copies into the destination string. The source-string argument is
    the address of a descriptor pointing to the source string.

 start-position

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference for CALL entry point, by value for JSB
                  entry point

    Relative position in the source string at which the substring
    that STR$RIGHT copies starts. The start-position argument is the
    address of a signed longword containing the starting position.

6.32  –  STR$ROUND

    The Round or Truncate a Decimal String routine rounds or
    truncates a decimal string to a specified number of significant
    digits and places the result in another decimal string.

    Format

      STR$ROUND  places ,flags ,asign ,aexp ,adigits ,csign ,cexp

                 ,cdigits

6.32.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.32.2  –  Arguments

 places

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Maximum number of decimal digits that STR$ROUND retains in the
    result. The places argument is the address of a signed longword
    containing the number of decimal digits.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Function flag. A value of 0 indicates that the decimal string is
    rounded; a value of 1 indicates that it is truncated. The flags
    argument is the address of an unsigned longword containing this
    function flag.

 asign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    Sign of the decimal input string to be rounded or truncated.
    The asign argument is the address of an unsigned longword string
    containing this sign. A value of 0 is considered positive; a
    value of 1 is considered negative.

 aexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       read only
    mechanism:    by reference

    Power of 10 by which adigits is multiplied to get the absolute
    value of the decimal input string. The aexp argument is the
    address of a signed longword containing this exponent.

 adigits

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Decimal input string. This is the string of digits to which asign
    and aexp are applied. The adigits argument is the address of a
    descriptor pointing to this numeric string. The string must be an
    unsigned decimal number.

 csign

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference

    Sign of the result. The csign argument is the address of an
    unsigned longword containing the result's sign. A value of 0
    is considered positive; a value of 1 is considered negative.

 cexp

    OpenVMS usage:longword_signed
    type:         longword (signed)
    access:       write only
    mechanism:    by reference

    Power of 10 by which cdigits is multiplied to get the absolute
    value of the result. The cexp argument is the address of a signed
    longword containing this exponent.

 cdigits

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Result's numeric text string. The cdigits argument is the address
    of a descriptor pointing to this numeric string. The string is an
    unsigned decimal number.

6.33  –  STR$TRANSLATE

    The Translate Matched Characters routine successively compares
    each character in a source string to all characters in a match
    string. If a source character has a match, the destination
    character is taken from the translate string. Otherwise,
    STR$TRANSLATE moves the source character to the destination
    string.

    Format

      STR$TRANSLATE  destination-string ,source-string

                     ,translation-string ,match-string

6.33.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.33.2  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string. The destination-string argument is the
    address of a descriptor pointing to the destination string.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string. The source-string argument is the address of a
    descriptor pointing to the source string.

 translation-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Translate string. The translation-string argument is the address
    of a descriptor pointing to the translate string.

 match-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Match string. The match-string argument is the address of a
    descriptor pointing to the match string.

6.34  –  STR$TRIM

    The Trim Trailing Blanks and Tabs routine copies a source string
    to a destination string and deletes the trailing blank and tab
    characters.

    Format

      STR$TRIM  destination-string ,source-string [,resultant-length]

6.34.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.34.2  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$TRIM copies the trimmed string.
    The destination-string argument is the address of a descriptor
    pointing to the destination string.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string which STR$TRIM trims and then copies into the
    destination string. The source-string argument is the address
    of a descriptor pointing to the source string.

 resultant-length

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference

    Number of bytes that STR$TRIM writes into destination-string,
    not counting padding in the case of a fixed-length string. The
    resultant-length argument is the address of an unsigned word
    into which STR$TRIM writes the length of the output string.
    If the input string is truncated to the size specified in the
    destination-string  description, resultant-length is set to
    this size. Therefore, resultant-length can always be used by
    the calling program to access a valid substring of destination-
    string.

6.35  –  STR$UPCASE

    The Convert String to All Uppercase Characters routine converts a
    source string to uppercase.

    Format

      STR$UPCASE  destination-string ,source-string

6.35.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

6.35.2  –  Arguments

 destination-string

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor

    Destination string into which STR$UPCASE writes the string it has
    converted to uppercase. The destination-string argument is the
    address of a descriptor pointing to the destination string.

 source-string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor

    Source string that STR$UPCASE converts to uppercase. The source-
    string argument is the address of a descriptor pointing to the
    source string.
Close Help