Set_Conversation_Security_Password (CPI-C)

Article
04/19/2022

The Set_Conversation_Security_Password call (function name cmscsp) is issued by the invoking program to specify the password required to gain access to the invoked program.

Syntax

  
CM_ENTRY Set_Conversation_Security_Password(   
  unsigned char FAR *conversation_ID,    
  unsigned char FAR *security_password,    
  CM_INT32 FAR *security_password_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_password
Supplied parameter. Specifies the password required to gain access to the partner program. This parameter is a character string of up to eight ASCII characters and is case-sensitive. It must match the password for the user identifier configured for the partner program.

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_password_length
Supplied parameter. Specifies the length of security_password. 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_password_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.

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

An invalid password 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 domain, but can be any platform that supports Host Integration 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 account under which the client is logged in, and substitutes the host account information into the APPC attach message it sends to the host.

Share via