Defines or clears passwords to be used for server-to-server connections.
CS_RETCODE ct_remote_pwd(connection, action, servername, srvlen,
passwd, pwd_len);
CS_CONNECTION *connection;
CS_INT action;
CS_CHAR *servername;
CS_INT srvnamelen;
CS_CHAR passwd;
CS_INT pwd_len;
(I) Handle for this connection. This connection handle must already be allocated with ct_con_alloc.
Remote passwords can only be defined for a connection that is not open. Passwords defined after a connection is open are ignored.
(I) Action to be taken by this call. action is an integer variable that indicates the purpose of this call. action can be any of the following symbolic values:
Value |
Meaning |
|---|---|
CS_SET (34) |
Sets the remote password. |
CS_CLEAR (35) |
Clears all remote passwords specified for this connection. |
(I) Name of the server for which the password is being defined. This is the name by which the server is known in the Server Path Table.
If action is CS_CLEAR, set servername to zeroes.
If servername is blank, the specified password is considered a “universal” password, to be used with any server that does not have a password explicitly specified for it.
(I) Length, in bytes, of servername. To use the default “universal” password, assign CS_NULL_STRING to this argument.
(I) Password being installed for remote logins to the server named in servername.
If action is CS_CLEAR, set passwd to zeroes, and the password defaults to the one set for this connection in ct_con_props, if any.
(I) Length, in bytes, of passwd.
ct_remote_pwd returns one of the following values:
Value |
Meaning |
|---|---|
CS_SUCCEED (-1) |
Results are available for processing. |
CS_FAIL (-2) |
The routine failed. |
TDS_INVALID_PARAMETER (-4) |
One or more of the ct_remote_pwd arguments contains an illegal value. Likely causes for this code are:
|
TDS_SOS (-257) |
Memory shortage. The operation failed. |
ct_remote_pwd defines the password that a server uses when logging into another server. An application can call ct_remote_pwd to clear remote passwords for a connection at any time.
A Transact-SQL language command or stored procedure or transaction running on one server can call a stored procedure or transaction located on another server. To accomplish this server-to-server communication, the first server, to which an application connects 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 use when the first server logs into the remote server.
Multiple passwords can be specified, one for each server that the first server might need to log into. Each password must be defined with a separate call to ct_remote_pwd.
If an application does not specify a remote password for a particular server, the password defaults to the password set for this connection through ct_con_props, if any. If a password is not defined, the password is set to zeroes. If an application user generally has the same password on different servers, this default behavior can be sufficient.
Remote passwords are stored in an internal buffer, which is only 255 bytes long. Each password 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.
Define remote passwords before calling ct_connect to create an active connection. It is an error to call ct_remote_pwd to define a remote password for a connection that is already open.
Related functions
