SSHCLIENTSUPPORT for ClearPath MCP provides an Application Program Interface (API) for users with special requirements to develop SSH client programs capable of issuing an EXEC command to a remote server. A user can exercise most features provided by the SSH client by modifying the provided example program, or by writing their own.

Linking to the SSHClient Library

The SSHClient functions are provided by the system library SYSTEM/SSHCLIENT/SUPPORT with the function name SSHCLIENTSUPPORT. For example, from the sample programs, linking to SSHCLIENTSUPPORT is done, as follows:

Library SSHCLIENTSUPPORT (LIBACCESS = BYFUNCTION, 
         FUNCTIONNAME = "SSHCLIENTSUPPORT.”);

Opening an SSH Client Session

After you have linked to the SSHCLIENTSUPPORT library, you can create an SSH session request with a remote system. This is done by calling the DCOpenSSHSession procedure, as follows:

Integer Procedure DCOpenSSHSession(
                iVersion,            % input
                UserAuth,            % input
                RemoteLogin,         % input
                RemotePassword,      % input
                SecureKeyContainer,  % input
                iPortNumber,         % input
                iVerbose,            % input
                Hostname,            % input
                RemoteCommand,       % input
                rUserTag,            % input
                iResponseType,       % input
                rResponseQueueToken, % input
                rErrorQueueToken,    % input
                iQueueVersion,       % input
                iFlags,              % input/output
                iSessionType,        % input
                bSSHCauseExceptionEvent, % input
                SSHSessionHandle,    % ouput
                SSHSessionResultText % ouput
                );

VALUE iVersion, iPortNumber, iVerbose,
      rUserTag, iResponseType, 
      rResponseQueueToken, rErrorQueueToken,
      iQueueVersion, iSessionType, 
      bSSHCauseExceptionEvent;

EBCDIC ARRAY UserAuth[0], RemoteLogin[0],
             RemotePassword [0], SecureKeyContainer[0], 
             Hostname[0], RemoteCommand[0], 
             SSHSessionHandle[0], SSHSessionResultText[0];

BOOLEAN bSSHCauseExceptionEvent;

INTEGER iVersion, iPortNumber, iVerbose,
        iResponseType, iQueueVersion, iFlags,
        iSessionType;

REAL rUserTag, rResponseQueueToken, rErrorQueueToken;

LIBRARY SSHCLIENTSUPPORT;

The following table describes the parameters used to call DCOpenSSHSession:

DCOpenSSHSession returns an integer as the procedure result. A return value of 0 indicates a successful result. Any other value represents an error. See “Tracing an Error Detection” for a detailed list of error codes.

Query the SSH Request Status

After DCOpenSSHSession has completed, the request may be queried to determine the state of the connection. Use GetSSHSessionStatus to query the connection state, as follows:

	Integer Procedure GetSSHSessionStatus (
						 iVersion,           % input
						 iFlags,             % input
						 SSHSessionHandle,   % input
						 SSHSessionResultText, % output
						 iSSHSessionSubResult  % output
);
VALUE iVersion;

EBCDIC ARRAY SSHSessionHandle[0], SSHSessionResultText[0];

INTEGER iVersion, iFlags, iSSHSessionSubResult;

LIBRARY SSHCLIENTSUPPORT;

The parameters for GetSSHSessionStatus are described below:

The following table describes the procedure results of GetSSHSession status.

Canceling the SSH Request

If a status request is pending or active, the request can be cancelled and the SSH session can be closed using the CloseSSHSession procedure. Requests that have completed, encountered an error, or are run when the library is not running are automatically closed and should not be closed by CloseSSHSession.

The CloseSSHSession procedure is declared, as follows:

Integer Procedure CloseSSHSession (
						                   iVersion,            % input
						                   iFlags,              % input
						                   SSHSessionHandle,    % input
						                   SSHSessionResultText %output
                                   );
VALUE iVersion;
			
EBCDIC ARRAY SSHSessionHandle[0], SSHSessionResultText[0];

INTEGER iVersion, iFlags;

LIBRARY SSHCLIENTSUPPORT;

The following table describes the parameters of the CloseSSHSession procedure:

CloseSSHSession returns an integer as the procedure result. A return value of 0 indicates a successful result. Any other value represents an error. See “Tracing an Error Detection” for a detailed list of error codes.

Tracing and Error Detection

The iVerbose parameter of DCOpenSSHSession is used to enable diagnostic tracing of an SSH session. Using an iVerbose setting of 2 or 3 provides additional diagnostic information which might be needed to determine the cause of an error. To determine the cause of an error, each procedure produces an error message string in the SSHSessionResultText. The procedure GetSSHSessionStatus also returns iSSHSessionSubResult with a detailed return code.

For the DCOpenSSHSession and CloseSSHSession procedures, a return value of 0 indicates a successful result. Any other value represents an error. Use the following table of error codes to determine the cause of any received error code.

SSHClient Example Program

The following example shows a sample SSHClient program.

BEGIN
 DEFINE
 SSH_SSHSessionResultText_LengthV     	= 126 #   % in bytes
,SSH_SSHSessionHandle_LengthV         	= 20 #    % in bytes
,SSH_RemoteLogin_LengthV              	= 257 #   % in bytes
,SSH_RemotePassword_LengthV          	= 257 #   % in bytes
,SSH_Hostname_LengthV                	= 257 #   % in bytes
,SSH_RemoteCommand_LengthV            = 342 #   % in bytes
,SSH_UserAuth_LengthV                 	= 57 #    % in bytes
,SEC_SecureKeyContainer_LengthV      	= 257 #   % in bytes
,SSH_Result_Ok                       		= 00 #

% STATUS Request Category

,SSH_Status_Queued                    = 1 #
,SSH_Status_InProgress                = 2 #
,SSH_Status_Completed               = 3 #
,SSH_Status_Down                        = 4 #
,SSH_Status_WaitingRetry           = 5 #
,SSH_Status_Error                         = 9 #
;
 
EBCDIC ARRAY
   UserAuth [0:SSH_UserAuth_LengthV-1]
  ,RemoteLogin [0:SSH_RemoteLogin_LengthV-1]
  ,RemotePassword [0:SSH_RemotePassword_LengthV-1]
  ,SecureKeyContainer [0:SEC_SecureKeyContainer_LengthV-1]
  ,Hostname [0:SSH_Hostname_LengthV-1]
  ,RemoteCommand [0:SSH_RemoteCommand_LengthV-1]
  ,SSHSessionHandle [0:SSH_SSHSessionHandle_LengthV-1]
  ,SSHSessionResultText [0:SSH_SSHSessionResultText_LengthV-1]
  ;

BOOLEAN
   bSSHCauseExceptionEvent;
INTEGER
   iVersion
  ,iPortNumber
  ,iVerbose
  ,iResponseType
  ,iQueueVersion
  ,iFlags
  ,iSessionType
  ,iSSHSessionSubResult
  ;

 REAL
   rUserTag,
   rResponseQueueToken,
   rErrorQueueToken;

Library SSHCLIENTSUPPORT
 (LIBACCESS = BYFUNCTION, FUNCTIONNAME = "SSHCLIENTSUPPORT."
               );

Integer Procedure DCOpenSSHSession (
%================================%
                                    iVersion,                
                                    UserAuth,                
                                    RemoteLogin,             
                                    RemotePassword,          
                                    SecureKeyContainer,
                                    iPortNumber,             
                                    iVerbose,                
                                    Hostname,                
                                    RemoteCommand,           
                                    rUserTag,                
                                    iResponseType,           
                                    rResponseQueueToken,     
                                    rErrorQueueToken,        
                                    iQueueVersion,           
                                    iFlags,                  
                                    iSessionType,            
                                    bSSHCauseExceptionEvent, 
                                    SSHSessionHandle,        
                                    SSHSessionResultText);   

VALUE iVersion, iPortNumber, iVerbose, rUserTag,
      iResponseType, rResponseQueueToken, rErrorQueueToken,
      iQueueVersion, iSessionType, bSSHCauseExceptionEvent;
EBCDIC ARRAY UserAuth [0], RemoteLogin [0], RemotePassword [0],
             SecureKeyContainer [0], Hostname [0], RemoteCommand [0],
             SSHSessionHandle [0], SSHSessionResultText [0];

BOOLEAN bSSHCauseExceptionEvent;

INTEGER iVersion, iPortNumber, iVerbose, iResponseType, iQueueVersion,
        iFlags, iSessionType;

REAL    rUserTag, rResponseQueueToken, rErrorQueueToken;

Library SSHCLIENTSUPPORT;

Integer Procedure CloseSSHSession (
%===============================%
                                   iVersion,                
                                   iFlags,                  
                                   SSHSessionHandle,        
                                   SSHSessionResultText);   

VALUE iVersion;

EBCDIC ARRAY SSHSessionHandle [0], SSHSessionResultText [0];

INTEGER iVersion, iFlags;

Library SSHCLIENTSUPPORT;

Integer Procedure GetSSHSessionStatus (
%===================================%
                                       iVersion,            
                                       iFlags
                                       SSHSessionHandle,     
                                       SSHSessionResultText,
                                       iSSHSessionSubResult);

VALUE iVersion;

EBCDIC ARRAY SSHSessionHandle [0], SSHSessionResultText [0];

INTEGER iVersion, iFlags, iSSHSessionSubResult;

Library SSHCLIENTSUPPORT;

Integer Result;


  iVersion := 1;  % reserved for future use, must equal 1.

  iResponseType := 2; % remote File response.
  % other valid responses are:  0 - No response                     %%
  %                             1 - Display                         %%
  %                             2 - Remote File                     %%
  %                             3 - Anonymous Token ** advanced **  %%
  %                             4 - Port Files ** advanced **       %%

  iSessionType := 2; % EXEC. Shell/Subfile are not supported.

  iQueueVersion := 1; % reserved for future use, must equal 1.

  iVerbose := 1; % request verbose response
  % valid Verbose options are : 0 - None
  %                             1 - Client Verbose Output
  %                             2 - Client and Library Verbose Output
  %                             3 - Most Verbose Output

  bSSHCauseExceptionEvent := TRUE;
replace RemoteLogin by "<usercode>", 48"00";
replace RemotePassword by "<password>", 48"00";
replace Hostname by "<hostname or ip>", 48"00"; 
replace RemoteCommand by "<command>", 48"00"; 
% replace SecureKeyContainer by "<SSH Key Container>", 48"00";
 %% uncomment the prior line and comment the line for RemotePassword %%
  %% to use public key authentication as opposed to password.         %%

  % See SSHCLIENT API documentation for Parameter Descriptions
  Result := DCOpenSSHSession(iVersion,
                             UserAuth,
                             RemoteLogin,
                             RemotePassword,
                             SecureKeyContainer,
                             iPortNumber,
                             iVerbose,
                             Hostname,
                             RemoteCommand,
                             rUserTag,
                             iResponseType,
                             rResponseQueueToken,
                             rErrorQueueToken,
                             iQueueVersion,
                             iFlags,
                             iSessionType,
                             bSSHCauseExceptionEvent,
                             SSHSessionHandle,
                             SSHSessionResultText);
 Display(SSHSessionResultText);
 Display(SSHSessionHandle);

 IF Result = SSH_Result_Ok Then
  Begin
 %% A timeout may be specified by uncommenting the following line and %%
 %% commenting out the current WAIT statement.                        %%
  % Wait((4),MYSELF.EXCEPTIONEVENT);
    Wait(MYSELF.EXCEPTIONEVENT); % Waits for bSSHCauseExceptionEvent
    Reset(MYSELF.EXCEPTIONEVENT);

    % See SSHCLIENT API Documentation for Parameter Descriptions
    Result := GetSSHSessionStatus(
                                  iVersion,
                                  iFlags,
                                  SSHSessionHandle,
                                  SSHSessionResultText,
                                  iSSHSessionSubResult);

    Case Result Of
     Begin % status has completed succesfully or in error.
     SSH_Status_Completed:
     SSH_Status_Down:
     SSH_Status_Error:
        Display(SSHSessionResultText);
    % status is active or pending. Cancel the request and close session
    SSH_Status_Queued:
    SSH_Status_InProgress:
    SSH_Status_WaitingRetry:
        Display(SSHSessionResultText);
        Result := CloseSSHSession(
                                  iVersion,
                                  iFlags,
                                  SSHSessionHandle,
                                  SSHSessionResultText);
        If Result = SSH_Result_Ok Then
         Display(SSHSessionResultText);
    Else:
    End Of Case;
   End
 Else
  Display(SSHSessionResultText);
End;
End.