Gets user login information from the client.
%INCLUDE SYGWPLI;
01 TDPROC PTR, 01 RETCODE FIXED BIN(31), 01 ACCESS_CODE CHAR(32), 01 USER_ID CHAR(32), 01 PASSWORD CHAR(32), 01 SERVER_NAME CHAR(32), 01 CLIENT_CHARSET CHAR(32), 01 NATIONAL_LANGUAGE CHAR(32), 01 SERVER_CHARSET CHAR(32), 01 SERVER_DBCS CHAR(32), 01 APPNAME_ID CHAR(32);
CALL TDGETUSR' (TDPROC, RETCODE, ACCESS_CODE,
USER_ID, PASSWORD, SERVER_NAME,
CLIENT_CHARSET, NATIONAL_LANGUAGE,
SERVER_CHARSET, SERVER_DBCS,
APPNAME_ID);
(I) Handle for this client/server connection. This must be the same value specified in the associated TDACCEPT call. The TDPROC handle corresponds to the connection and command handles in Open Client Client-Library.
(O) Variable where the result of function execution is returned. Its value is one of the codes listed in Table 3-11.
(I) Variable containing an access code that authorizes this application to retrieve a client password. TDGETUSR gets this information from the mainframe customization module.
(O) Variable where the client user ID is returned to the application. This is the user ID the client uses to log into the TRS.
(O) Variable where the client password is returned to the application. This is the password the client uses to log into the TRS.
If an access code is required and it does not match
the access code specified during mainframe customization, the PASSWORD field
is set to blanks.
(O) Variable where the name of the server specified by the client is returned. For workstation clients, this is the name of the TRS used to access this Open ServerConnect application.
(O) Variable where the name of the character set used by the client is returned. This information is provided in the client login packet.
(O) Variable where the name of the national language used by the client is returned. This information is provided in the client login packet. If no national language is specified, the default is U.S. English.
(O) Variable where information about the treatment of single-byte characters is returned. This value is set during customization.
If SERVER_DBCS indicates that double-byte character sets are not supported (SERVER_DBCS is NONE), SERVER_CHARSET returns the name of the default single-byte character set used by Gateway-Library programs. The default character set is used in the following cases:
The client login packet does not specify a character set.
The client login packet specifies a character set, but Gateway-Library cannot find that character set in the table of character set names.
If SERVER_DBCS indicates that double-byte character sets are supported (SERVER_DBCS is KANJI), SERVER_CHARSET indicates how single-byte characters are treated.
Single-byte characters can be treated as either:
LOWERCASE |
Lowercase letters (roman alphabet) |
KANA |
Hankaku katakana (single-byte Japanese characters) |
(O) DBCS support indicator. This value indicates whether the mainframe system is using double-byte kanji characters or only single-byte characters. TDGETUSR gets this information from the mainframe customization module.
KANJI |
Double-byte characters are supported. |
NONE |
Double-byte characters are not supported. |
(O) Name of the client application (from the client login record). The application name is set on the client side via a dbsetlapp call, and forwarded to the mainframe by the TRS. APPNAME_ID is typically used to pass unique identifier information about the client application.
The RETCODE argument can contain any of the return values listed in Table 3-11.
Return value |
Meaning |
|---|---|
TDS_OK (0) |
Function completed successfully. |
TDS_CONNECTION_TERMINATED (-4997) |
Connection closed. The remote partner closed (deallocated) the client/server connection. |
TDS_INVALID_PARAMETER (-4) |
Invalid parameter value. The value assigned to one or more of the arguments supplied in the call is not valid. The operation failed. |
TDS_INVALID_TDPROC (-18) |
Error in specifying a value for the TDPROC argument. |
The following code fragment illustrates the use of TDGETUSR to verify the client login information. The program must provide an access code—TOP SECRET—for permission to access the user’s password. It is taken from the sample program in Appendix B, “Sample RPC Application for CICS.”
/* ------------------------------------------------------------*/
/* accept client request */
/* ------------------------------------------------------------*/
CALL TDACCEPT (GWL_PROC, GWL_RC, GWL_INIT_HANDLE,
SNA_CONNECTION_NAME,
SNA_SUBC);
/* ------------------------------------------------------------*/
/* TDRESULT to validate kicked off via rpc request */
/* ------------------------------------------------------------*/
CALL TDRESULT (GWL_PROC, GWL_RC);
IF GWL_RC ^= TDS_PARM_PRESENT THEN
DO;
CALL TDRESULT_ERROR;
GO TO END_PROGRAM;
END;
/* ------------------------------------------------------------*/
/* verify user login information */
/* ------------------------------------------------------------*/
GU_ACCESS_CODE = 'TOP SECRET';
CALL TDGETUSR (GWL_PROC, GWL_RC,
GU_ACCESS_CODE,
GU_USER_ID,
GU_PASSWORD,
GU_SERVER_NAME,
GU_CLIENT_CHARSET,
GU_NATIONAL_LANG,
GU_SERVER_CHARSET,
GU_SERVER_DBCS,
GU_APP_ID);
IF GWL_RC ^= TDS_OK THEN
DO;
CALL TDGETUSR_ERROR;
GO TO END_PROGRAM;
END;
TDGETUSR allows a mainframe server application to retrieve client information from the login packet. This information includes:
The user ID and password the client used to log into the TRS
The name of the TRS through which the request is sent
The national language used by the client
The character set used by the client
TDGETUSR retrieves customization information from the mainframe customization module. This information includes:
The default single-byte character set used by Gateway-Library
How single-byte characters are treated in DBCS
A security access code that must be entered to retrieve users’ login passwords
TDGETUSR is especially useful to customers who provide their own security or accounting functions. It enables the program to uniquely identify each user of the Open ServerConnect product or application.
TDGETUSR prevents unauthorized access to a client password by requiring an access code. Unless the correct access code is specified in the ACCESS_CODE argument, the password is not returned to the variable specified in PASSWORD. In this case, TDGETUSR returns TDS_OK, but leaves PASSWORD blank.
You can deactivate this feature, allowing the program
to retrieve the password without an access code.
Related topics
Related functions
