Set_Conversation_Security_User_ID

The Set_Conversation_Security_User_ID call (function name cmscsu) is issued by the invoking program to specify the user identifier required to gain access to the invoked program.

CM_ENTRY Set_Conversation_Security_User_ID(
  unsigned char FAR *conversation_ID,  
  unsigned char FAR *security_user_ID,  
  CM_INT32 FAR *security_user_ID_length,  
  CM_INT32 FAR *return_code            
);
 

Parameters

conversation_ID

Supplied parameter. Specifies the identifier for the conversation. The value of this parameter was returned by Initialize_Conversation.

security_user_ID

Supplied parameter. Specifies the user identifier required to gain access to the partner program. This parameter is a character string of up to eight ASCII characters and is case-sensitive.

The allowed characters are:

• Uppercase and lowercase letters.
• Numerals 0 through 9.
• Special characters, except the space.

If the CPI-C automatic logon feature is to be used, this parameter must be set to the MS$SAME string. See the Remarks section for details.

security_user_ID_length

Supplied parameter. Specifies the length of security_user_ID. The range is from 1 through 8.

If the CPI-C automatic logon feature is to be used, this parameter must be set to 7. See the Remarks section for details.

return_code

The code returned from this call. The valid return codes are listed below.

Return Codes

cm_ok

Primary return code; the call executed successfully.

cm_program_parameter_check

Primary return code; one of the following occurred:

• The value specified by conversation_ID is invalid.
• The value specified by security_user_ID_length is out of range.

cm_program_state_check

Primary return code; one of the following occurred:

• The conversation is not in INITIALIZE state.
• The conversation's security type is not set to CM_SECURITY_PROGRAM.

cm_product_specific_error

Primary return code; a product-specific error occurred and has been logged in the product's error log.

State Changes

The conversation must be in INITIALIZE state.

There is no state change.

Remarks

This call has an effect on the conversation only if the conversation security type is CM_SECURITY_PROGRAM. It overrides the initial user identifier from the side information specified by Initialize_Conversation. This call cannot be issued after Allocate has been issued.

An invalid user identifier is not detected until the allocation request, generated by Allocate, is sent to the partner LU. The error is returned to the invoking program on a subsequent call.

Automatic logon for CPI-C applications is supported by Microsoft® SNA Server 3.0 with Service Pack 1 or later and by SNA Server 4.0. This feature requires specific configuration by the network administrator: The CPI-C application must be invoked on the LAN side from a client of SNA Server. The client must be logged into a Microsoft® Windows NT® domain, but can be any platform that supports SNA Server's CPI-C APIs.

The client application is coded to use "program" level security, with a special hard-coded CPI-C user name MS$SAME and password MS$SAME. When this session allocation flows from client to SNA Server, the SNA server looks up the host account and password corresponding to the Windows NT account under which the client is logged in, and substitutes the host account information into the APPC attach message it sends to the host.