Functions, 122 of 177

SYS_CONTEXT

Syntax

sys_context::=

Text description of functions183.gif follows

Purpose

SYS_CONTEXT returns the value of parameter associated with the context namespace. You can use this function in both SQL and PL/SQL statements.

For namespace and parameter, you can specify either a string (constant) or an expression that resolves to a string designating a namespace or an attribute. The context namespace must already have been created, and the associated parameter and its value must also have been set using the DBMS_SESSION.set_context procedure. The namespace must be a valid SQL identifier. The parameter name can be any string. It is not case sensitive, but it cannot exceed 30 bytes in length.

The datatype of the return value is VARCHAR2. The default maximum size of the return value is 256 bytes. You can override this default by specifying the optional length parameter. The valid range of values is 1 to 4000 bytes. (If you specify an invalid value, then Oracle ignores it and uses the default.)

Oracle9i provides a built-in namespace called USERENV, which describes the current session. The predefined parameters of namespace USERENV are listed Table 6-2 , along with the lengths of their return strings.

Restriction on SYS_CONTEXT

You cannot specify this function in a parallel query.

See Also:

Oracle9i Application Developer's Guide - Fundamentals for information on using the application context feature in your application development
CREATE CONTEXT for information on creating user-defined context namespaces
Oracle9i Supplied PL/SQL Packages and Types Reference for information on the DBMS_SESSION.set_context procedure

Examples

The following statement returns the name of the user who logged onto the database:

CONNECT OE/OE
SELECT SYS_CONTEXT ('USERENV', 'SESSION_USER') 
   FROM DUAL;

SYS_CONTEXT ('USERENV', 'SESSION_USER')
------------------------------------------------------
OE

The following hypothetical example returns the group number that was set as the value for the attribute group_no in the PL/SQL package that was associated with the context hr_apps when hr_apps was created:

SELECT SYS_CONTEXT ('hr_apps', 'group_no') "User Group" 
   FROM DUAL;

Table 6-2 Predefined Parameters of Namespace USERENV

Parameter	Return Value	Return Length (bytes)
`AUDITED_CURSORID`	Returns the cursor ID of the SQL that triggered the audit.	NA
`AUTHENTICATION_DATA`	Data being used to authenticate the login user. For X.503 certificate authenticated sessions, this field returns the context of the certificate in HEX2 format. Note: You can change the return value of the `AUTHENTICATION_DATA` attribute using the `length` parameter of the syntax. Values of up to 4000 are accepted. This is the only attribute of `USERENV` for which Oracle implements such a change.	256
`AUTHENTICATION_TYPE`	How the user was authenticated: `DATABASE`: user name/password authentication `OS`: operating system external user authentication `NETWORK`: network protocol or ANO authentication `PROXY`: OCI proxy connection authentication	30
`BG_JOB_ID`	Job ID of the current session if it was established by an Oracle background process. Null if the session was not established by a background process.	64
`CLIENT_IDENTIFIER`	Returns the client session identifier in the global context--that is, the globally accessed application context or (in the OCI context) the `OCI_ATTR_CLIENT_IDENTIFIER` attribute. If no globally relevant identifier has been set, returns null.	NA
`CLIENT_INFO`	Returns up to 64 bytes of user session information that can be stored by an application using the `DBMS_APPLICATION_INFO` package.	64
`CURRENT_SCHEMA`	Name of the default schema being used in the current schema. This value can be changed during the session with an `ALTER` `SESSION` `SET` `CURRENT_SCHEMA` statement.	30
`CURRENT_SCHEMAID`	Identifier of the default schema being used in the current session.	30
`CURRENT_SQL`	Returns the current SQL that triggered the fine-grained auditing event. You can specify this attribute only inside the event handler for the Fine-Grained Auditing feature.	64
`CURRENT_USER`	The name of the user whose privilege the current session is under.	30
`CURRENT_USERID`	User ID of the user whose privilege the current session is under.	30
`DB_DOMAIN`	Domain of the database as specified in the `DB_DOMAIN` initialization parameter.	256
`DB_NAME`	Name of the database as specified in the `DB_NAME` initialization parameter.	30
`ENTRY_ID`	The available auditing entry identifier. You cannot use this attribute in distributed SQL statements. To use this keyword in `USERENV`, the initialization parameter `AUDIT_TRAIL` must be set to `TRUE`.	30
`EXTERNAL_NAME`	External name of the database user. For SSL authenticated sessions using v.503 certificates, this field returns the distinguished name (DN) stored in the user certificate.	256
`FG_JOB_ID`	Job ID of the current session if it was established by a client foreground process. Null if the session was not established by a foreground process.	30
`GLOBAL_CONTEXT_MEMORY`	Returns the number being used in the System Global Area by the globally accessed context.	NA
`HOST`	Name of the host machine from which the client has connected.	54
`INSTANCE`	The instance identification number of the current instance.	30
`IP_ADDRESS`	IP address of the machine from which the client is connected.	30
`ISDBA`	Returns `TRUE` if the user has been authenticated as having DBA privileges either through the operating system or through a password file.	30
`LANG`	The ISO abbreviation for the language name, a shorter form than the existing '`LANGUAGE`' parameter.	62
`LANGUAGE`	The language and territory currently used by your session, along with the database character set, in this form: language_territory.characterset	52
`NETWORK_PROTOCOL`	Network protocol being used for communication, as specified in the '`PROTOCOL`=`protocol`' portion of the connect string.	256
`NLS_CALENDAR`	The current calendar of the current session.	62
`NLS_CURRENCY`	The currency of the current session.	62
`NLS_DATE_FORMAT`	The date format for the session.	62
`NLS_DATE_LANGUAGE`	The language used for expressing dates.	62
`NLS_SORT`	`BINARY` or the linguistic sort basis.	62
`NLS_TERRITORY`	The territory of the current session.	62
`OS_USER`	Operating system user name of the client process that initiated the database session.	30
`PROXY_USER`	Name of the database user who opened the current session on behalf of `SESSION_USER`.	30
`PROXY_USERID`	Identifier of the database user who opened the current session on behalf of `SESSION_USER`.	30
`SESSION_USER`	Database user name by which the current user is authenticated. This value remains the same throughout the duration of the session.	30
`SESSION_USERID`	Identifier of the database user name by which the current user is authenticated.	30
`SESSIONID`	The auditing session identifier. You cannot use this attribute in distributed SQL statements.	30
`TERMINAL`	The operating system identifier for the client of the current session. In distributed SQL statements, this attribute returns the identifier for your local session. In a distributed environment, this is supported only for remote `SELECT` statements, not for remote `INSERT`, `UPDATE`, or `DELETE` operations. (The return length of this parameter may vary by operating system.)	10