OCIDescribeAny()

Purpose

Describes existing schema and sub-schema objects.

Syntax

sword OCIDescribeAny ( OCISvcCtx       *svchp,
                       OCIError        *errhp,
                       dvoid           *objptr,
                       ub4             objptr_len,
                       ub1             objptr_typ,
                       ub1             info_level,
                       ub1             objtyp,
                       OCIDescribe     *dschp );

Parameters

svchp (IN)

A service context handle.

errhp (IN/OUT)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

objptr (IN)

This parameter can be:

1. A string containing the name of the object to be described. Must be UTF16 encoded in OCI_UTF16 environment.

2. A pointer to a REF to the TDO (for a type).

3. A pointer to a TDO (for a type).

These cases are distinguished by passing the appropriate value for objptr_typ. This parameter must be non-null.

In case 1, the string containing the object name should be in the format name1[.name2 ...][@linkname], such as scott.emp.empno@mydb. Database links are only allowed to Oracle8i or later databases. The object name is interpreted by the following SQL rules:

• If only name1 is entered and objtyp is equal to OCI_PTYPE_SCHEMA, then the name refers to the named schema. The Oracle database must be release 8.1 or later.

• If only name1 is entered and objtyp is equal to OCI_PTYPE_DATABASE, then the name refers to the named database. When describing a remote database with database_name@db_link_name, the remote Oracle database must be release 8.1 or later.

• If only name1 is entered and objtyp is not equal to OCI_PTYPE_SCHEMA or OCI_PTYPE_DATABASE, then the name refers to the named object (of type table / view / procedure / function / package / type / synonym / sequence) in the current schema of the current user. When connected to an Oracle7 Server, the only valid types are procedure and function.

• If name1.name2.name3 ... is entered, the object name refers to a schema/sub-schema object in the schema named name1. For example, in the string scott.emp.deptno, scott is the name of the schema, emp is the name of a table in the schema, and deptno is the name of a column in the table.

objnm_len (IN)

The length of the name string pointed to by objptr. Must be nonzero if a name is passed. Can be zero if objptr is a pointer to a TDO or its REF.

objptr_typ (IN)

The type of object passed in objptr. Valid values are:

• OCI_OTYPE_NAME, if objptr points to the name of a schema object

• OCI_OTYPE_REF, if objptr is a pointer to a REF to a TDO

• OCI_OTYPE_PTR, if objptr is a pointer to a TDO

info_level (IN)

Reserved for future extensions. Pass OCI_DEFAULT.

objtyp (IN)

The type of schema object being described. Valid values are:

• OCI_PTYPE_TABLE, for tables

• OCI_PTYPE_VIEW, for views

• OCI_PTYPE_PROC, for procedures

• OCI_PTYPE_FUNC, for functions

• OCI_PTYPE_PKG, for packages

• OCI_PTYPE_TYPE, for types

• OCI_PTYPE_SYN, for synonyms

• OCI_PTYPE_SEQ, for sequences

• OCI_PTYPE_SCHEMA, for schemas

• OCI_PTYPE_DATABASE, for databases

• OCI_PTYPE_UNK, for unknown schema objects

dschp (IN/OUT)

A describe handle that is populated with describe information about the object after the call. Must be non-null.

Comments

This is a generic describe call that describes existing schema objects: tables, views, synonyms, procedures, functions, packages, sequences, types, schemas, and databases. This call also describes sub-schema objects, such as a column in a table. This call populates the describe handle with the object-specific attributes which can be obtained through an OCIAttrGet() call.

An OCIParamGet() on the describe handle returns a parameter descriptor for a specified position. Parameter positions begin with 1. Calling OCIAttrGet() on the parameter descriptor returns the specific attributes of a stored procedure or function parameter, or a table column descriptor. These subsequent calls do not need an extra round-trip to the server because the entire schema object description is cached on the client side by OCIDescribeAny(). Calling OCIAttrGet() on the describe handle also returns the total number of positions.

If the OCI_ATTR_DESC_PUBLIC attribute is set on the describe handle, then the object named is looked up as a public synonym when the object does not exist in the current schema and only name1 is specified.

See Also: For more information about describe operations, see Chapter 6, "Describing Schema Metadata"

Related Functions

OCIAttrGet(), OCIParamGet()