Edit

Share via

Set_Conversation_Security_User_ID (CPI-C)

  • Article

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.

Syntax

  
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 from 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. For details, see the Remarks section later in this topic.

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

    If the CPI-C automatic logon feature is to be used, this parameter must be set to 7. For details, see the Remarks section later in this topic.

    return_code
    The code returned from this call. The valid return codes are listed later in this topic.

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 conversations 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 products 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 or CM_SECURITY_SAME. 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 logical unit (LU). The error is returned to the invoking program on a subsequent call.

Automatic logon for CPI-C applications is supported by Host Integration Server. 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 Server domain, but can be any platform that supports SNA Server 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 Server account under which the client is logged on, and substitutes the host account information into the APPC attach message it sends to the host.