Set_Conversation_Security_Type

The Set_Conversation_Security_Type call (function name cmscst) is issued by the invoking program to specify the information the partner LU requires to validate access to the invoked program.

CM_ENTRY Set_Conversation_Security_Type(
  unsigned char FAR *conversation_ID,        
  CM_INT32 FAR *conversation_security_type,  
  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.

conversation_security_type

Supplied parameter. Specifies the information the partner LU requires to validate access to the invoked program. Based on the conversation security established for the invoked program during configuration, use one of the following values:

CM_SECURITY_NONE

To indicate that the invoked program uses no conversation security.

CM_SECURITY_PROGRAM

To indicate that the invoked program uses conversation security and thus requires a user identifier and password.

CM_SECURITY_SAME

To specify that the invoked program, invoked with a valid user identifier and password, in turn invokes another program (as illustrated in Communication Between TPs). For example, assume that program A invokes program B with a valid user identifier and password, and program B in turn invokes program C. If program B specifies the value CM_SECURITY_SAME, CPI-C will send the LU for program C, the user identifier from program A, and an already-verified indicator. This indicator tells program C not to require the password (if program C is configured to accept an already-verified indicator).

If the CPI-C automatic logon feature is to be used, this parameter must be set to CM_SECURITY_PROGRAM. 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_state_check

Primary return code; the conversation is not in INITIALIZE state.

cm_program_parameter_check

Primary return code; the value specified by conversation_ID or conversation_security_type is invalid.

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 overrides the initial security type from the side information specified by Initialize_Conversation. This call cannot be issued after Allocate has been issued.

If the conversation security type is set to cm_security_none or cm_security_same, the user identifier and password are ignored when the conversation is allocated.

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.