ct_con_drop  ct_config

Chapter 3: Routines

ct_con_props

Description

Set or retrieve connection structure properties.

Syntax

CS_RETCODE ct_con_props(connection, action, property,
                buffer, buflen, outlen)
 
 CS_CONNECTION    *connection;
 CS_INT                       action;
 CS_INT                       property;
 CS_VOID                    *buffer;
 CS_INT                       buflen;
 CS_INT                        *outlen;

Parameters

connection

A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular client/server connection.

action

One of the following symbolic values:

Value of action

Result

CS_SET

Sets the value of the property.

CS_GET

Retrieves the value of the property.

CS_CLEAR

Resets the property to its default value.

CS_SUPPORTED

Checks whether a distributed-service driver supports the property. Use only with properties that affect the behavior of a directory or security driver. See “Checking whether a property is supported”.
property

The symbolic name of the property whose value is being set or retrieved. Table 3-12 lists the properties that can be set with ct_con_props. “Properties” lists all Client-Library properties.

buffer

If a property value is being set, buffer points to the value to use in setting the property.

buflen

Generally, buflen is the length, in bytes, of *buffer.

If *buffer is a fixed-length or symbolic value, pass buflen as CS_UNUSED.

outlen

A pointer to an integer variable.

outlen is not used if a property value is being set and should be passed as NULL.

If a property value is being retrieved and outlen is supplied, ct_con_props sets *outlen to the length, in bytes, of the requested information.

If the information is larger than buflen bytes, an application can use the value of *outlen to determine how many bytes are needed to hold the information.

Returns

ct_con_props returns the following values:

Return value

Meaning

CS_SUCCEED

The routine completed successfully.

CS_FAIL

The routine failed.

CS_BUSY

An asynchronous operation is already pending for this connection. See “Asynchronous programming”.

Examples

Example 1

This code excerpt is from the blktxt.c sample program.

        /*



         ** EstablishConnection()

         **

         ** Purpose:

         ** This routine establishes a connection to the server 

         ** identified in example.h and sets the CS_USER,

         ** CS_PASSWORD, and CS_APPNAME properties for the 

         ** connection.

         **

         ** NOTE: The user name, password, and server are defined

         ** in the example header file.

         */

        CS_STATIC CS_RETCODE

         EstablishConnection(context, connection)

         CS_CONTEXT      *context;

         CS_CONNECTION   *connection;

         {

             CS_INT      len;

             CS_RETCODE  retcode;

             CS_BOOL     bool;

            /* Allocate a connection structure */

             ...CODE DELETED.....

            /*    

             ** If a user name is defined in example.h, set the 

             ** CS_USERNAME property.

             */

             if (retcode == CS_SUCCEED && Ex_username != NULL)

             {

                 if ((retcode = ct_con_props(*connection, CS_SET,

                     CS_USERNAME, Ex_username, CS_NULLTERM, NULL))

                     != CS_SUCCEED)

                 {

                     ex_error("ct_con_props(username) failed");

                 }

             }

            /*    

             ** If a password is defined in example.h, set the 

             ** CS_PASSWORD property.

             */

             if (retcode == CS_SUCCEED && Ex_password != NULL)

             {

                 if ((retcode = ct_con_props(*connection, CS_SET,

                     CS_PASSWORD, Ex_password, CS_NULLTERM, NULL))

                     != CS_SUCCEED)

                 {

                     ex_error("ct_con_props(passwd) failed");

                 }

             }

            /* Set the CS_APPNAME property */

             ...CODE DELETED.....

            /* Enable the bulk login property */

             if (retcode == CS_SUCCEED)

             {

                 bool = CS_TRUE;

                 retcode = ct_con_props(*connection, CS_SET,

                     CS_BULK_LOGIN, &bool, CS_UNUSED, NULL);

                 if (retcode != CS_SUCCEED)

                 {

                      ex_error("ct_con_props(bulk_login) failed");

                 }

             }

            /* Open a server connection */

             ...CODE DELETED.....

        }

Example 2

In the following example, CS_SEC_EXTENDED_ENCRYPTION is disabled:

...
CS_INT Ex_encryption = CS_FALSE;
CS_INT Ex_nonencryptionretry = CS_FALSE;
...
main()
{
    ...
    /*
    
    ** This needs to be called before calling ct_connect()
    */
     ret = ct_con_props(connection, CS_SET, CS_SEC_EXTENDED_ENCRYPTION,
           &Ex_encryption, CS_UNUSED, NULL);
    EXIT_ON_FAIL(context, ret, "Could not set extended encryption");
    ret = ct_con_props(connection, CS_SET, CS_SEC_NON_ENCRYPTION_RETRY,
          &Ex_nonencryptionretry, CS_UNUSED, NULL);
    EXIT_ON_FAIL(context, ret, "Could not set non encryption retry");
    ...
}

Usage

For information about action, buffer, buflen, and outlen, see Chapter 2, “Understanding Structures, Constants, and Conventions,” in the Open Client Client-Library/C Programmers Guide.

See also

ct_capability, ct_cmd_props, ct_connect, ct_config, ct_init, “Properties”




Copyright © 2009. Sybase Inc. All rights reserved. ct_config

View this document as PDF