Package com.compuware.api.topaz.hostconnections.zos

Interface IZOSUserProgramConnection

  • All Superinterfaces:
    IHostConnection
    public interface IZOSUserProgramConnection
extends IHostConnection
    A connection to a z/OS user program.

    z/OS user program connections are used to launch and communicate with z/OS user programs.

    launchUserProgram(IZOSCredentials, String, String) must be called in order to establish a connection to the associated z/OS host and launch a user program. getInputStream() and getOutputStream() should not be called until a connection to the associated z/OS host has been established and a user program is executing. Only one user program may be executing on a z/OS user program connection at once.

    Examples:
    To launch a z/OS user program: 

     IZOSHost zosHost = ...
 String userID = ...
 String password = ...
 String userProcedureName = ...
 String userProgramName = ...
 
 // use one of the several ZOSCredentialsFactory methods to create a z/OS
 // credentials object
 IZOSCredentials credentials = ZOSCredentialsFactory
         .createZOSCredentials(userID, password);
 
 // create a z/OS user program connection from the z/OS host
 IZOSUserProgramConnection zosUserProgramConnection = zosHost
         .createZOSUserProgramConnection();
 
 try {
     // launch the z/OS user program
     zosUserProgramConnection.launchUserProgram(credentials,
             userProcedureName, userProgramName);
     
     // the z/OS user program connection is now able to communicate with the
     // program (for as long as it remains running)
     ...
 } catch (HostCredentialsException e) {
     // credentials were invalid, likely caused by incorrect login
     // information or expired password
     ...
 }
    Note: If writing a plug-in that runs in a Topaz Workbench installation, you can use the ZOSUIUserCredentialsManager class in the com.compuware.api.topaz.eclpse plug-in to retrieve the credentials of the currently logged in Topaz Workbench UI user. See com.compuware.api.topaz.eclipse.hostcredentials.zos.ZOSUIUserCredentialsManager for more details.

    For examples on how to obtain IZOSHosts see IZOSHost.
    For examples on how to send data to a z/OS user program see getOutputStream().
    For examples on how to receive data from a z/OS user program see getInputStream().
    For examples on how to listen to z/OS user program termination events see IZOSUserProgramTerminationListener.

    Since:
    1.0.0
    Version:
    2.0.0
    Restriction:
    This interface is not intended to be extended by clients.
    Restriction:
    This interface is not intended to be implemented by clients.

    • Method Detail

      • getHost

        IZOSHost getHost()
        Returns the z/OS host associated with this z/OS user program connection.
        Specified by:
        getHost in interface IHostConnection
        Returns:
        the z/OS host
        Since:
        1.0.0

      • getUserProgramName

        String getUserProgramName()
        Returns the name of the currently executing z/OS user program.
        Returns:
        the name of the currently executing z/OS user program, or null if no z/OS user program is currently executing
        Since:
        1.0.0

      • getUserProcedureName

        String getUserProcedureName()
        Returns the name of the currently executing z/OS user procedure.
        Returns:
        the name of the currently executing z/OS user procedure, or null if no z/OS user procedure is currently executing
        Since:
        1.0.0

      • isUserProgramExecuting

        boolean isUserProgramExecuting()
        Returns whether a z/OS user program is currently executing.
        Returns:
        true if a z/OS user program is currently executing, false otherwise
        Since:
        1.0.0

      • getInputStream

        InputStream getInputStream()
        Returns an input stream that can be used to read data from an executing z/OS user program.

        An input stream can only be obtained after the z/OS user program is launched.

        The returned input stream is only valid for the z/OS user program for which it is associated.

        The input stream treats the termination of the z/OS user program as the end of the stream. (Any data sent prior to termination will still be accessible via this input stream.)

        As long as the same z/OS user program is executing, this method will return the same input stream. Care should be taken to prevent multiple threads from using this input stream at the same time.

        Note: all of InputStream's read methods will block until the z/OS user program sends data, is terminated, or an IOException occurs.

        Examples:
        To read byte data from a z/OS user program: 

         IZOSUserProgramConnection zosUserProgramConnection = ...
 byte[] buffer = ...
 
 try {
     // get the z/OS user program's input stream
     // Note: a z/OS user program must be executing before calling this method
     InputStream inputStream = zosUserProgramConnection.getInputStream();
 
     // use any of the input stream's "read" methods to read data
     int numBytesRead = inputStream.read(buffer);
 } catch (IOException e) {
     // an IO error occurred reading data from the input stream
     ...
 }
        To read text data from a z/OS user program: 
         IZOSUserProgramConnection zosUserProgramConnection = ...
 
 try {
     // get the z/OS user program's input stream
     // Note: a z/OS user program must be executing before calling this method
     InputStream inputStream = zosUserProgramConnection.getInputStream();
 
     // wrap the z/OS user program's input stream in a buffered reader
     // Note: this code assumes the z/OS user program is encoding its data
     // using UTF-8
     BufferedReader reader = new BufferedReader(new InputStreamReader(
             inputStream, "UTF-8"));
 
     // use the any of the reader's "read" methods to read text from the
     // z/OS user program
     String data = reader.readLine();
 } catch (IOException e) {
     // an IO error occurred wrapping the input stream or reading data from it
     ...
 }
        For examples on how to launch a z/OS user program, see IZOSUserProgramConnection.
        For examples on how to send data to a z/OS user program, see getOutputStream().
        Returns:
        the input stream
        Throws:
        UserProgramNotExecutingException - if a z/OS user program is not currently executing
        Since:
        1.0.0
        See Also:
        isUserProgramExecuting(), getOutputStream()

      • getOutputStream

        OutputStream getOutputStream()
        Returns an output stream that can be used to write data to an executing z/OS user program.

        An output stream can only be obtained after the z/OS user program is launched.

        The returned output stream is only valid for the z/OS user program for which it is associated.

        The output stream becomes invalid when the z/OS user program is terminated.

        As long as the same z/OS user program is executing, this method will return the same output stream. Care should be taken to prevent multiple threads from using this output stream at the same time.

        Examples:
        To send byte data to a z/OS user program: 

         IZOSUserProgramConnection zosUserProgramConnection = ...
 byte[] data = ...
 
 try {
     // get the z/OS user program's output stream
     // Note: a z/OS user program must be executing before calling this method
     OutputStream outputStream = zosUserProgramConnection.getOutputStream();
 
     // use any of the output stream's "write" methods to write data
     outputStream.write(data);
 } catch (IOException e) {
     // an IO error occurred writing data to the output stream
     ...
 }
        To send text data to a z/OS user program: 
         IZOSUserProgramConnection zosUserProgramConnection = ...
 String data = ...
 
 try {
     // get the z/OS user program's output stream
     // Note: a z/OS user program must be executing before calling this method
     OutputStream outputStream = zosUserProgramConnection.getOutputStream();
 
     // wrap the z/OS user program's output stream in a buffered writer
     // Note: this code assumes the z/OS user program is decoding received
     // data using UTF-8
     BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(
             outputStream, "UTF-8"));
 
     // use any of the writer's "write" methods to write text to the user
     // program
     writer.write(data);
 
     // flush the writer to ensure the data gets sent to the z/OS user program
     writer.flush();
 } catch (IOException e) {
     // an IO error occurred wrapping the output stream or writing data to it
     ...
 }
        For examples on how to launch a z/OS user program see IZOSUserProgramConnection.
        For examples on how to receive data from a z/OS user program see getInputStream().
        Returns:
        the output stream
        Throws:
        UserProgramNotExecutingException - if a z/OS user program is not currently executing
        Since:
        1.0.0
        See Also:
        isUserProgramExecuting(), getInputStream()