ort.h

ORACLE访问接口

/* @(#)ort.h	1.44 95/07/07 */

/* Copyright (c) Oracle Corporation 1994, 1995, 1996, 1997, 1999.  All Rights Reserved. */

/* 
  NAME

    ORT - ORacle's external open Type interface to the open type manager (OTM)

  DESCRIPTION

    The open type manager interface includes dynamic type operations to
    create, delete, update, and access types.  See the "Functional
    Specification for Oracle Object Call Interface (Objects Project),
    Version 1.0" for a user level description of the OTM.  For a more
    detailed description, see the "Component Document for the Open Type
    Manager, Version 1.0".

    NOTE: MOST Of the functions in this header file are being desupported.
          Please use the OCIDescribeAny interface as described in oci.h
          instead.
          The OCIType, OCITypeElem, OCITypeMethod abstract types continue
          to be supported. The only two functions that remain to be documented
          are OCITypeArrayByName and OCITypeArrayByRef.
          All obsolete types/functions are marked accordingly below.

  RELATED DOCUMENTS

    For the functional specification for the OTM, see: 
        [1] Kotsovolos, Susan, "Functional Specification for Oracle Object
            Call Interface (Objects Project), Version 1.0", Oracle
            Corporation, February 1995.
    For the internal design of the OTM, see the following:
        [2] Kotsovolos, Susan, "Component Document for the Open Type Manager",
            Oracle Corporation, November 1994. 
        [3] Kotsovolos, Susan, "Design for The Open Type Manager, Oracle 
            Object Management Subsystem Version 1.0", Oracle Corporation, 
            March 1994.
        [4] Kotsovolos, Susan and Tin A. Nguyen, "The Open Type Manager",
            Oracle Corporation, March 1994.
        [5] Kotsovolos, Susan and Tin A. Nguyen, "Schema Evolution",
            Oracle Corporation, March 1994.
    For a description of the types the OTM must support, see:
        [6] Nguyen, Tin A., "The Open Type System", Oracle Corporation, 
            February 1994. 

  INSPECTION STATUS 

    Inspection date:    
    Inspection status: 
    Estimated increasing cost defects per page:
    Rule sets:        

  ACCEPTANCE REVIEW STATUS 

    Review date:    
    Review status:
    Reviewers:  


  **** ALL OBSOLETE FUNCTIONS/TYPES ARE MARKED ACCORDINGLY ***

  EXPORT FUNCTIONS

    None

  PUBLIC DATA STRUCTURES

      OCIType - type descriptor in the object cache
      OCITypeElem - type element descriptor in the object cache
            (used for attributes and paramters)
      OCITypeCode  - Open Type System type code.
      OCITypeMethod - method descriptor in the object cache
      OCITypeParamMode - parameter modes (ie. IN, IN-OUT etc)

  PUBLIC FUNCTIONS

    ITERATOR (for OCITypeAttrNext and OCITypeMethodNext)

      OCITypeIterNew  - ** OBSOLETE ** Create new instance of an iteraton.
      OCITypeIterSet  - ** OBSOLETE ** Initialize iterator.
      OCITypeIterFree - ** OBSOLETE ** Free instance of iterator.

    TYPE GET

      OCITypeByName      - ** OBSOLETE ** Get a type by name.
      OCITypeArrayByName - Get an array of types by their names.
      OCITypeByRef       - ** OBSOLETE ** Get a type by its CREF.
      OCITypeArrayByRef  - Get an array of types by their CREFs.

    TYPE ACCESSORS

      OCITypeName     - ** OBSOLETE ** OCI Get a type's name.
      OCITypeSchema   - ** OBSOLETE ** OCI Get a type's schema name.
      OCITypeTypeCode - ** OBSOLETE ** OCI Get a type's type code.
      OCITypeVersion  - ** OBSOLETE ** OCI Get a Type's user-readable Version.
      OCITypeAttrs    - ** OBSOLETE ** OCI Get a Type's Number of Attributes.
      OCITypeMethods  - ** OBSOLETE ** OCI Get a Type's Number of Methods.

    TYPE ELEMENT ACCESSORS (they represent attributes/parameters/results)

      OCITypeElemName      - ** OBSOLETE ** Get a type element's (only for
                                attributes) name.
      OCITypeElemType      - ** OBSOLETE ** Get a type element's type
                                descriptor.
      OCITypeElemTypeCode  - ** OBSOLETE ** Get a type element's typecode.
      OCITypeElemParameterizedType - ** OBSOLETE ** Get a type element's
                                        parameterized type's type descriptor.
      OCITypeElemNumPrec   - ** OBSOLETE ** Get a number's precision.
      OCITypeElemNumScale  - ** OBSOLETE ** Get a decimal or oracle Number's
                                            Scale
      OCITypeElemCharSetID - ** OBSOLETE ** Get a fixed or variable length
                                            string's character set ID.
      OCITypeElemCharSetForm - ** OBSOLETE ** Get a fixed or variable length
                                              string's character set form (how
                                              character set information has
                                              been specified).
      OCITypeElemLength    - ** OBSOLETE ** Get a raw, fixed or variable
                                            length string's length.
      OCITypeElemParamMode - ** OBSOLETE ** Get element's parameter's mode
                                            (only valid for parameter).
      OCITypeElemDefaultValue - ** OBSOLETE ** Get element's Default Value.

    ATTRIBUTE ACCESSORS

      OCITypeAttrByName - ** OBSOLETE ** Get an Attribute by Name.
      OCITypeAttrNext   - ** OBSOLETE ** Get an Attribute by Iteration.

    COLLECTION ACCESSORS

      OCITypeCollTypeCode - ** OBSOLETE ** Get a named collection's typecode.
      OCITypeCollElem     - ** OBSOLETE ** Get a named collection's element's
                               type element information.
      OCITypeCollSize     - ** OBSOLETE ** Get a named collection's size in
                               number of elements.

    METHOD ACCESSORS

      OCITypeMethodOverload - ** OBSOLETE ** Get number of overloaded methods
                                             with the given method name.
                                             (no direct equivalent for
                                              OCIDescribe interface)
      OCITypeMethodByName   - ** OBSOLETE ** Get one or more methods by name.
      OCITypeMethodNext     - ** OBSOLETE ** Iterate to the next method to
                                             retrieve.
      OCITypeMethodName     - ** OBSOLETE ** Get method's name.
      OCITypeMethodEncap    - ** OBSOLETE ** Get method's encapsulation level. 
      OCITypeMethodFlags    - ** OBSOLETE ** et method's flags.
      OCITypeMethodMap      - ** OBSOLETE ** Get type's map function.
      OCITypeMethodOrder    - ** OBSOLETE ** Get type's order function.
      OCITypeMethodParams   - ** OBSOLETE ** Get a method's number of
                                             parameters.

    RESULT ACCESSORS

      OCITypeResult - ** OBSOLETE ** OCI Get a method's Result.

      See also ATTRIBUTE/PARAMETER/RESULT TYPE ACCESSORS.

    PARAMETER ACCESSORS

      OCITypeParamByPos  - ** OBSOLETE ** Get a Parameter in a method By
                                          Position.
      OCITypeParamByName - ** OBSOLETE ** Get a Parameter in a method By Name.
      OCITypeParamPos    - ** OBSOLETE ** Get a Parameter's PoSition in a
                                          method.

  CALL GRAPHS:

  Only type accessors are supported for 8.0.
  ** OBSOLETE ** please use OCIDescribe interface

  TYPE ACCESSOR EXAMPLE

      CREATE TYPE CAR
      (
        name   vstring,
        age    number,
          number   car_age;                           /o Oracle number o/
          weight   car_weight;                        /o abstract type o/

        PUBLIC: 

          /o methods o/
          car(orlvs a_name, number an_age, WEIGHT a_weight);
          ~car();
          inline number get_age() const;
          
          /o relative ordering (map) functions o/
          number car_map
      );

      /o the following code accesses the type created above o/

      ub1      meth_flags;
      ub4      i, j; 
      ub4      text_len, position;
      ub4      count;
      ub4      length;
      OCITypeCode    typecode;
      OCIRef  *attr_ref;
      OCIRef  *param_ref;
      OCIType  *tdo, new_tdo, final_tdo;
      OCITypeElem  *elem;
      OCITypeIter  *iterator;
      text   (*names)[];
      ub4      lengths[];
      ub4     *positions;
      text    *name;
      text     name_buffer[M_IDEN];

      /o initialize the references o/
      DISCARD orlrini(env, err, (dvoid *)&attr_ref);
      DISCARD orlrini(env, err, (dvoid *)&param_ref);

      /o ----------------- GET INFORMATION ABOUT A TYPE ----------------- o/

      /o start a transaction o/
      
      /o Pin the type until the end of the transaction.  Pinning the type is 
       o required before using any type accessors. 
       o/
      if (OCITypeByName(env, err, svc, (text *)0, 0, "CAR", strlen("CAR"), 
                  OCI_DURATION_TRANS, &car_ref, &car_tdo) != OCI_SUCCESS)
        /o error o/ ;

      /o get the type's name o/
      if (!memcmp(OCITypeName(env, err, car_tdo, &text_len), "person",
                              text_len))
        /o do something o/ ;

      /o get the type's schema name o/
      if (!memcmp(OCITypeSchema(env, err, car_tdo, &text_len), "john",
                  text_len))
        /o do something o/ ;

      /o get the type code of the type o/
      if (OCITypeTypeCode(env, err, car_tdo) == OCI_TYPECODE_ADT)
        /o do something o/ ; 

      /o get the type version o/
      if (!memcmp(OCITypeVersion(env, err, car_tdo, &text_len), "1", text_len))
         /o do something o/  ;

      /o ------- GET FLATTENED POSITION OF AN ATTRIBUTES IN A TYPE ------- o/

      names = malloc(sizeof(text *) * 2);
      names[0] = malloc(strlen("car_weight"));
      names[1] = malloc(strlen("ounces"));
      memcpy(names[0], "car_weight", strlen("car_weight"));
      memcpy(names[1], "ounces", strlen("ounces"));

      lengths = malloc(sizeof(ub4) * 2);
      lengths[0] = strlen("car_weight");
      lengths[1] = strlen("ounces");

      /o ---------- GET IMMEDIATE ATTRIBUTES IN A TYPE ---------- o/

      /o loop through all attributes in the type with iterator o/
      if (OCITypeIterNew(env, err, car_tdo, &iterator) != OCI_SUCCESS)
        /o do something o/

      while (OCITypeAttrNext(env, err, iterator, &ado) != OCI_NO_DATA)
      {
        /o get the attribute's name o/
        if (!memcmp(OCITypeElemName(env, err, ado, &text_len),
                                    "tiger", text_len))
          /o do something o/  ;

        /o get the attribute's type descriptor o/
        if (OCITypeElemType(env, err, ado, &tdo) != OCI_SUCCESS)
          /o error o/ ;

        /o get the attribute's type code o/
        typecode = OCITypeElemTypeCode(env, err, ado);

        switch (typecode)
        {
        /o scalar types o/
        case OCI_TYPECODE_DATE:                                     /o date o/
        case OCI_TYPECODE_SIGNED8:                                  /o byte o/
        case OCI_TYPECODE_SIGNED16:                                /o short o/
        case OCI_TYPECODE_UNSIGNED8:                       /o unsigned byte o/
        case OCI_TYPECODE_UNSIGNED16:                     /o unsigned short o/
        case OCI_TYPECODE_OCTET:                                   /o octet o/
        case OCI_TYPECODE_TABLE:                            /o nested table o/
        case OCI_TYPECODE_CLOB:                            /o character lob o/
        case OCI_TYPECODE_BLOB:                               /o binary lob o/
        case OCI_TYPECODE_CFILE:                   /o character file object o/
        case OCI_TYPECODE_BFILE:                      /o binary file object o/

          /o do something o/
          break;

        /o number types o/