4
Ensuring Future Compatibility with Evolving interMedia Object Types

The interMedia object types may evolve by adding new object attributes in a future release. Client-side applications that want to maintain compatibility with the current release of the interMedia object types (ORDAudio, ORDImage, ORDVideo, and ORDSource), even after a server upgrade that includes evolved object types, are advised to do the following:

• Make a call to the compatibility initialization function at the beginning of the application, if necessary (see Section 4.1).
• Use the static constructor functions, init( ), in INSERT statements that are provided beginning with release 8.1.7 (see Section 6.2, Section 8.1.1, and Section 9.2). Do not use the default constructors because INSERT statements using the default constructor will fail if the interMedia object types have added new attributes.

  Note: If you do not do the preceding recommended actions, you may have to upgrade your client and perhaps even recompile your application when you upgrade to a newer server release with evolved types.

4.1 When and How to Call the Compatibility Initialization Function

Only client-side applications that statically recognize the structure of the interMedia object types need to make a call to the compatibility initialization function. Server-side stored procedures will automatically use the newly installed (potentially changed) interMedia object types after an upgrade, so you do not need to call the compatibility initialization function from server-side stored procedures.

Client-side applications that do not statically (at compile time) recognize the structure of interMedia object types do not need to call the compatibility initialization function. OCI applications that determine the structure of the interMedia object types at runtime, through the OCIDescribeAny call, do not need to call the compatibility initialization function.

Client-side applications written in OCI that have been compiled with the C structure of interMedia object types (generated by OTT) should make a call to the server-side PL/SQL function, ORDSYS.IM.compatibilityInit( ), at the beginning of the application. See the compatibilityInit( ) method description of this function in this section.

Client-side applications written in Java using the interMedia Java Classes for release 8.1.7 or higher, should call the OrdMediaUtil.imCompatibilityInit( ) function after connecting to the Oracle database server.

public static void imCompatibilityInit(OracleConnection con)
    throws Exception

This Java function takes OracleConnection as an argument. The included interMedia release 8.1.7 or higher Java API will ensure that your 8.1.7 or higher application will work (without upgrading) with a potential future release of interMedia with evolved object types.

There is not yet a way for client-side PL/SQL applications to maintain compatibility with the current release of the interMedia object types if the objects add new attributes in a future release.

See the compatibilityInit( ) method in this section, and Oracle interMedia Java Classes User's Guide and Reference for further information, and detailed descriptions and examples. This guide is on the Oracle Technology Network, http://otn.oracle.com/.

---

compatibilityInit( )

Format

compatibilityInit(release IN VARCHAR2,

errmsg OUT VARCHAR2)

RETURN NUMBER;

Description

Allows for compatibly evolving the interMedia object types in a future release.

Parameters

release

The release number. This string should be set to '9.0.1' to allow a 9.0.1 application to work (without upgrading) with a potential future release of the Oracle database and interMedia with evolved object types.

errmsg

String output parameter. If the function returns a status other than 0, this errmsg string contains the reason for the failure.

Pragmas

None.

Exceptions

None.

Usage Notes

You should begin using the compatibilityInit( ) method as soon as possible to ensure you will not have to upgrade the Oracle software on your client node, or recompile your client application in order to work with a future release of the Oracle database server if the interMedia object types change in a future release. See Section 4.1 to determine if you need to call this function.

The compatibility initialization function for interMedia is located in the ORDSYS.IM package.

Examples

Using OCI and setting the compatibilityInit( ) method release parameter to release 9.0.1 to allow a 9.0.1 application to work with a future release of the Oracle database and interMedia with changed object types; note, that this is not a standalone program in that it assumes that you have allocated handles beforehand:

void prepareExecuteStmt( OCIEnv *envHndl,
             OCIStmt **stmtHndl,
             OCIError *errorHndl,
             OCISvcCtx *serviceCtx,
             OCIBind *bindhp[] )
{
   text *statement = (text *)
      "begin :sts := ORDSYS.IM.compatibilityInit( :vers, :errText );
end;";
  sword sts = 0;
  text *vers = (text *)"9.0.1";
  text errText[512];
  sb2 nullInd;

  printf( " Preparing statement\n" );

  OCIHandleAlloc( envHndl, (void **) stmtHndl, OCI_HTYPE_STMT, 0, NULL
);

  OCIStmtPrepare( *stmtHndl, errorHndl, (text *)statement,
         (ub4)strlen( (char *)statement ), OCI_NTV_SYNTAX,
         OCI_DEFAULT );

  printf( " Executing statement\n" );

  OCIBindByPos( *stmtHndl, &bindhp[ 0 ], errorHndl, 1, (void *)&sts,
        sizeof( sts ), SQLT_INT, (void *)0, NULL, 0, 0,
        NULL, OCI_DEFAULT );

  OCIBindByPos( *stmtHndl, &bindhp[ 1 ], errorHndl, 2, vers,
        strlen((char *)vers) + 1, SQLT_STR, (void *)0, NULL,
        0, 0, NULL, OCI_DEFAULT );

  OCIBindByPos( *stmtHndl, &bindhp[ 2 ], errorHndl, 3, errText,
        sizeof( errText ), SQLT_STR, &nullInd, NULL, 0, 0,
        NULL, OCI_DEFAULT);

  OCIStmtExecute( serviceCtx, *stmtHndl, errorHndl, 1, 0,
        (OCISnapshot *)NULL, (OCISnapshot *)NULL, OCI_DEFAULT );

  printf( " Statement executed\n" );
  if (sts != 0)
    {
    printf( "CompatibilityInit failed with Sts = %d\n", sts );
    printf( "%s\n", errText );
    }


}