smc_connect_props

Description

Sets, retrieves, or clears properties on a connection.

Syntax

SMC_RETURN_CODE smc_connect_props
 (SMC_CONNECT_ID       clientId,
 	SMC_PROP_ACTION      propertyAction,
 	SMC_PROP_TYPE        property,
 	SMC_VALUE_UNIONP     propertyValue,
 	SMC_SIZET            bufferLength,
 	SMC_SIZETP           outputLengthHandle)

Parameters

clientId

identifies the connection.

propertyAction

Property action type. Valid types are:

• SMC_PROP_ACT_CLEAR – reset the value of the specified property to its default.

• SMC_PROP_ACT_GET – retrieve the value of the specified property.

• SMC_PROP_ACT_SET – set the value of the specified property.

property

the symbolic name of the property whose value is being set, retrieved, or cleared. See Table 3-5 for a list of this argument’s legal values.

propertyValue

if propertyAction is:

• SMC_PROP_ACT_CLEAR – propertyValue is ignored.

• SMC_PROP_ACT_GET – pointer to the union in which smc_connect_props will place the requested information.

• SMC_PROP_ACT_SET – pointer to the union that contains the value to which property is to be set.

bufferLength

the length of data in bytes of *(propertyValue->stringValue). Used only if propertyValue is a pointer to a string. If propertyAction is:

• SMC_PROP_ACT_CLEAR – bufferLength is ignored, and must be passed SMC_UNUSED.

• SMC_PROP_ACT_GET – bufferLength is ignored, and must be passed SMC_UNUSED.

• SMC_PROP_ACT_SET – bufferLength must contain the number of bytes of *(propertyValue-> stringValue) or SMC_NULLTERM to indicate the string’s length by a terminating null byte.

outputLengthHandle

a pointer to an integer variable. Used only if propertyValue is a pointer to a string. If propertyAction is:

• SMC_PROP_ACT_CLEAR – outputLengthHandle is ignored, and must be passed null.

• SMC_PROP_ACT_GET – the length in bytes of the requested information. Contains the number of bytes that were actually written to propertyValue->stringValue (not including the null-terminating byte). Pass null if this information is not desired.

• SMC_PROP_ACT_SET – outputLengthHandle is ignored, and must be passed null.

Returns

Examples

Example 1

This example assumes that you have previously allocated a connection using smc_connect_alloc and have a clientId.

SMC_VALUE_UNION  value.sizetValue = 512;
 if (smc_connect_props(clientId,
     SMC_PROP_ACT_SET,
     SMC_PROP_PACKETSIZE,
     &value,
     0,
     NULL) != SMC_RET_SUCCESS) 
 {
 		printf("smc_connect_props failed\n");
 		/* do some cleanup */
 }

Usage

• A property resets to its default value when cleared.

• smc_connect_props must be called after smc_connect_alloc.

• The following properties must be set on a connection before calling smc_connect_ex:

  • SMC_PROP_PASSWORD

  • SMC_PROP_SERVERNAME

  • SMC_PROP_USERNAME

• The serverMode determines which other Monitor Client Library functions are applicable for the connection. For example, smc_create_recording_session is not applicable for a live connection.

• The serverMode (specified upon creation of a connection) determines the behavior of the common functions. For example, smc_create_view can be used to create a live view or a historical view.

• For live connections and historical connections for defining recording sessions, the property SMC_PROP_USERNAME must be set to either “sa”, the name of an Adaptive Server account having sa_role, or the name of an Adaptive Server account with execute permission on the stored procedure master.dbo.mon_rpc_connect.

• To retrieve only the length of a string, pass null for propertyValue and a valid pointer for outputLengthHandle.

• For the definition of a SMC_VALUE_UNION structure, see “Union: SMC_VALUE_UNION”.

• For data of type SMC_CHARP, stringValue points to the value. The Monitor Client Library allocates the memory for this string and the calling application must deallocate it using free().

• The following properties are only valid before a connection is made:

  • SMC_PROP_APPNAME

  • SMC_PROP_IFILE

  • SMC_PROP_PASSWORD

  • SMC_PROP_SERVERMODE

  • SMC_PROP_SERVERNAME

  • SMC_PROP_USERNAME.

  If these properties are changed on a connection after it has been established, they take effect during the next call to smc_connect_ex.

• Table 3-5 summarizes the Monitor Client Library properties, whether they can be set, retrieved, or cleared, and the datatype of each property value:

Properties

Valid server modes

Errors

See also

smc_connect_alloc, smc_connect_ex

---

Copyright © 2001. Sybase Inc. All rights reserved.

View this book as PDF