ct_remote_pwd

Description

Define or clear passwords to be used for server-to-server connections.

Syntax

CS_RETCODE ct_remote_pwd(connection, action,
                  server_name, snamelen, password,
                  pwdlen)
 
CS_CONNECTION   *connection;
CS_INT                     action;
CS_CHAR                 *server_name;
CS_INT                      snamelen;
CS_CHAR                 *password;
CS_INT                      pwdlen;

Parameters

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

It is illegal to define remote passwords for a connection that is open.

action: One of the following symbolic values:

Value of action

Result

CS_SET

Sets the remote password

CS_CLEAR

Clears all remote passwords specified for this connection by setting them to NULL.

Value of action	Result
CS_SET	Sets the remote password
CS_CLEAR	Clears all remote passwords specified for this connection by setting them to NULL.

server_name: A pointer to the name of the server for which the password is being defined. *server_name is the name given to the server in an interfaces file.

If server_name is NULL, the specified password will be considered a universal password, to be used with any server that does not have a password explicitly specified.

If action is CS_CLEAR, server_name must be NULL.

snamelen: The length, in bytes, of *server_name. If *server_name is null-terminated, pass snamelen as CS_NULLTERM.

If action is CS_SET and server_name is NULL, pass snamelen as 0 or CS_UNUSED.

If action is CS_CLEAR, snamelen must be CS_UNUSED.

password: A pointer to the password being installed for remote logins to the *server_name server.

If action is CS_CLEAR, password must be NULL.

pwdlen: The length, in bytes, of *password. If *password is null-terminated, pass pwdlen as CS_NULLTERM.

If action is CS_SET and password is NULL, pass pwdlen as 0 or CS_UNUSED.

If action is CS_CLEAR, pwdlen must be CS_UNUSED.

Returns

ct_remote_pwd 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”.

Usage

ct_remote_pwd defines the password that a server will use when logging into another server.

A Transact-SQL language command or stored procedure running on one server can execute a stored procedure located on another server. To accomplish this server-to-server communication, the first server, to which an application has connected through ct_connect, actually logs into the second, remote server, performing a server-to-server remote procedure call.

ct_remote_pwd allows an application to specify the password to be used when the first server logs into the remote server.
Multiple passwords may be specified, one for each server that a server might need to log in to. Each password must be defined with a separate call to ct_remote_pwd.
An application can specify a universal password for server-to-server communication by calling ct_remote_pwd with a NULL server_name and the password value. Once the connection is open, the connection’s server uses this password to log in to any remote server for which a server-name/password pair was not specified with ct_remote_pwd.

If an application does not specify any remote server passwords, then Client-Library sends the connection password as the default universal password for server-to-server communication. The connection password is set through ct_con_props(CS_PASSWORD) and defaults to NULL. So, if an application user has the same password on different servers, the application need not call ct_remote_pwd.

However, if the application specifies a password for any particular server, then the application must explicitly define a universal password. For example, the following code specifies “tigger2” as the password for the “honey_tree” server and specifies “christopher” as the universal password to be used with any other remote server:
```
/*
```
```
 ** User’s password is "tigger2" on the "honey_tree" server.
```
```
 */
```
```
 retcode = ct_remote_pwd(conn, CS_SET, "honey_tree", CS_NULLTERM,
```
```
                        "tigger2", CS_NULLTERM);
```
```
 if (retcode != CS_SUCCEED)
```
```
       ... handle the error ...
```
```
 
```
```
 /*
```
```
 ** User’s password is "christopher" everywhere else.
```
```
 */
```
```
 retcode = ct_remote_pwd(conn, CS_SET, (CS_CHAR *) NULL, 0
```
```
                        "christopher", CS_NULLTERM);
```
```
 if (retcode != CS_SUCCEED)
```
```
       ... handle the error ...
```
Remote passwords are stored in an internal buffer which is only 255 bytes long. Each password’s entry in the buffer consists of the password itself, the associated server name, and two extra bytes. If the addition of a password to this buffer would cause overflow, ct_remote_pwd returns CS_FAIL and generates a Client-Library error message that indicates the problem.
It is an error to call ct_remote_pwd to define a remote password for a connection that is already open. Define remote passwords before calling ct_connect to create an active connection.
An application can call ct_remote_pwd to clear remote passwords for a connection at any time.