Defines or clears passwords to be used for server-to-server connections.
%INCLUDE CTPUBLIC; DCL 01 CONNECTION FIXED BIN(31) INIT(0); 01 RETCODE FIXED BIN(31) INIT(0); 01 ACTION FIXED BIN(31) INIT(1); 01 SERVERNAMECHAR(30); 01 SRV_LEN FIXED BIN(31); 01 SRV_BLANKSTRIP FIXED BIN(31); 01 PASSWDCHAR(30); 01 PWD_LEN FIXED BIN(31); 01 PWD_BLANKSTRIP FIXED BIN(31); CALL CTBREMOT (CONNECTION, RETCODE, ACTION, SERVERNAME, SRV_LEN, SRV_BLANKSTRIP, PASSWD, PWD_LEN, PWD_BLANKSTRIP);
(I) Handle for this connection. This connection handle must already be allocated with CTBCONALLOC.
Remote passwords can only be defined for a connection before it is open. Passwords defined after a connection is open are ignored.
(O) Variable where the result from an executed function returns. Its value is one of the codes listed under “Returns,” in this section.
(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 zeroes, the specified password will be 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. To indicate that the value is terminated at the last non-blank character, assign CS_TRUE to SRVBLANKSTRIP.
(I) Blank stripping indicator. Indicates whether the value in the buffer is terminated at the last non-blank character. Assign this argument one of the following symbolic values:
Value |
Meaning |
|---|---|
CS_TRUE (1) |
Trailing blanks are stripped. The value in the buffer ends at the last non-blank character. |
CS_FALSE (0) |
Trailing blanks are not stripped. They are included in the value. |
(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 CTBCONPROPS, if any.
(I) Length, in bytes, of PASSWD. To indicate that the value is terminated at the last non-blank character, assign CS_TRUE to PWDBLANKSTRIP.
(I) Blank termination indicator. Indicates whether the value of the password is terminated at the last non-blank character.
Assign this argument one of the following symbolic values:
Value |
Meaning |
|---|---|
CS_TRUE (1) |
Trailing blanks are stripped. The value in the buffer ends at the last non-blank character. |
CS_FALSE (0) |
Trailing blanks are not stripped. They are included in the value. |
CTBREMOTEPWD 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 CTBREMOTEPWD arguments contains an illegal value. Likely causes for this code are:
|
TDS_SOS (-257) |
Memory shortage. The operation failed. |
CTBREMOTEPWD defines the password that a server uses when it logs into another server. An application can call CTBREMOTEPWD to clear remote passwords for a connection at any time.
A Transact-SQL language command, 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 connected through CTBCONNECT, actually logs in to the second, remote server, performing a server-to-server remote procedure call.
CTBREMOTEPWD allows an application to specify the password to be used when the first server logs in to the remote server.
Multiple passwords can be specified, one for each server that the first server might need to log in to. Each password must be defined with a separate call to CTBREMOTEPWD.
If an application does not specify a remote password for a particular server, the password defaults to the password set for this connection through CTBCONPROPS, 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, CTBREMOTEPWD returns CS_FAIL and generates a Client-Library error message that indicates the problem.
Define remote passwords before calling CTBCONNECT to create an active connection. It is an error to call CTBREMOTEPWD to define a remote password for a connection that is already open.
Related functions:
