CONNECTION_EXTENDED_PROPERTY function [String]

Returns the value of the given property. Allows an optional property-specific string parameter to be specified.

Syntax

CONNECTION_EXTENDED_PROPERTY( 
{ property-id | property-name }
[, property-specific-argument [, connection-id ] ]
)

Parameters

property-id
The connection property ID.
property-name
The connection property name. The supported property names are:
- CharSet
  Returns the CHAR character set label for the connection as it is known by the specified standard. The possible values include: ASE, IANA, MIME, JAVA, WINDOWS, UTR22, IBM, and ICU. The default is IANA unless the database connection was made through TDS in which case ASE is the default.
- NcharCharSet
  Returns the NCHAR character set label for the connection as it is known by the specified standard. The possible values are the same as listed above for CharSet.
- HasSecuredFeature Returns Yes if at least one of the features in the property-specific-argument argument is secured for the connection, otherwise returns No. Returns NULL if property-specific-argument is NULL.
- Progress
  Returns information about how long a statement has been executing. Specify a property-specific-argument, followed by connection-id, to return information specific to the statement's progress.
property-specific-argument
An optional property-specific string parameter associated with the following connection property:
- HasSecuredFeature feature-list
  Specify a list of features to determine whether at least one of these features is secured.
- Progress
  - PercentComplete
    Specify PercentComplete to obtain the percentage of the statement that has been processed.
  - Completed
    Specify Completed to obtain the completed number of units.
  - Total
    Specify Total to obtain the total number of units left to be processed.
  - Units
    Specify Units to obtain the type of units left to be processed (pages, rows, or bytes).
  - Elapsed
    Specify Elapsed to obtain the current elapsed time in milliseconds.
  - Remaining
    Specify Remaining to obtain the estimated remaining time in milliseconds.
  - Raw
    Specify Raw to obtain a string combining all of the above values in the order listed, separated by semicolons. For example, 43;9728;22230;pages;5025;6138.
  - Formatted
    Specify Formatted to obtain the human readable format. For example:
    
    43% ( 9728 of 22230 pages ) complete after 00:00:05; estimated 00:00:06 remaining
    
    The Remaining value may be empty if the remaining time has not yet been estimated, or if the number of units completed is greater than the original estimate.
  For all property-specific arguments except Formatted, large byte values are never converted to kilobytes or megabytes.
connection-id
The connection ID number of a database connection. The ID number for the current connection is used if a value is not specified.

Returns

Returns extended connection properties. The returned value is a VARCHAR.

Remarks

Either the property ID or the property name must be specified.

The CONNECTION_EXTENDED_PROPERTY function is similar to the CONNECTION_PROPERTY function except that it allows an optional property-specific string parameter to be specified. The interpretation of the property-specific argument depends on the property ID or name specified in the first argument.

You can use the CONNECTION_EXTENDED_PROPERTY function to return the value for any connection property. However, extended information is only available for the extended properties.

Privileges

No privileges are required to execute this function for the current connection ID. To execute this function for other connections, you must have either the SERVER OPERATOR, MONITOR, or DROP CONNECTION system privilege.

NULL is returned if you specify an invalid parameter value or don't have one of the required system privileges.

Standards

ANSI/ISO SQL Standard
Not in the standard.

Example

The following example returns the CHAR character set of the current connection as it is known by the Java standard:

SELECT CONNECTION_EXTENDED_PROPERTY( 'charset', 'Java' );