-LINE COMPONENTS GUIDE PIPELINE PILOT INTEGRATION COLLECTION 2017 Copyright Notice

©2016 Dassault Systèmes. All rights reserved. 3DEXPERIENCE, the Compass icon and the 3DS logo, CATIA, SOLIDWORKS, ENOVIA, DELMIA, SIMULIA, GEOVIA, EXALEAD, 3D VIA, BIOVIA and NETVIBES are commercial trademarks or registered trademarks of Dassault Systèmes or its subsidiaries in the U.S. and/or other countries. All other trademarks are owned by their respective owners. Use of any Dassault Systèmes or its subsidiaries trademarks is subject to their express written approval.

Acknowledgments and References

To photographs or files of computational results (figures and/or data) obtained using BIOVIA software, acknowledge the source in an appropriate . For example: "Computational results obtained using software programs from Dassault Systèmes BIOVIA. The ab initio calculations were performed with the DMol3 program, and graphical displays generated with Pipeline Pilot."

BIOVIA may grant permission to republish or reprint its copyrighted materials. Requests should be submitted to BIOVIA Support, either through electronic mail to [email protected], or in writing to:

BIOVIA Support 5005 Wateridge Vista Drive, San Diego, CA 92121 USA Contents

Chapter 1: Introduction 1 Run Program 1 FTP 1 Telnet 1 SSH 1 SCP 2 Additional Information 2 Chapter 2: Run Program 3 Using Run Program in Protocols 3 Chapter 3: Protocol 6 Running a Protocol with an FTP Component 6 Chapter 4: Telnet 8 Chapter 5: SCP and SSH 9 Running a Protocol with a SCP and SSH Components 9 Chapter 1: Introduction

The Pipeline Pilot Integration collection includes a variety of components that let you execute third- party applications and file transfer services as command-line protocol interfaces. The following components are available for this purpose: Run Program FTP Telnet SSH SCP

Run Program You can extend the functionality of a protocol to include any operation that you can invoke from a Windows command line. Run Program (on Client) and Run Program (on ) components are available for this purpose. These components provide a way for you to execute an command on the server or on a client. For example, you can write data files, invoke the command line program to work on these files, and then read the results when the protocol is complete.

FTP (FTP) is used to transfer files over a TCP/IP network (Internet, UNIX, etc.). Components are available that support FTP ( File from Remote Host and Copy File to Remote Host). These components allow you to copy files from a server on your network to (or from) the server. Since these components use the FTP protocol, a valid user name and password are required as parameter values. Typically, FTP components are used in conjunction with Telnet or SOAP components to run programs on a remote machine.

Telnet Telnet is a terminal emulation method used on the Internet and TCP/IP-based networks. It allows a user to log onto a remote computer and run a program or execute UNIX commands. The Run Command on Remote Host (Telnet) component supports Telnet. It is written in Perl and uses the ::Telnet package. Required parameters for the component include username and password. Typically, this component is used with the FTP components to transfer input and result files to and from the remote host.

SSH Secure Shell (SSH) is a security protocol for logging on to a remote server. SSH provides an encrypted session for transferring files and executing server programs. SSH supports a variety of authentication methods and it provides a secure client/server connection for applications. Components are available that support SSH. The Run Command (SSH) component runs a command on a remote machine running SSH daemon and encrypts communication with the remote host. A password or key file is required as a parameter value for this component. The Manage Host Trust (SSH & SCP) component validates or

Introduction | Page 1 updates a key signature in a known host file, which allows you to verify the identity of the remote host before sending the encrypted password.

SCP Secure Copy Protocol (SCP) is a secure version of the UNIX remote (rcp) command for transmitting files to or from a remote machine. Unlike FTP, SCP encrypts all communication with the remote host. Components are available that support SCP (SCP File from Remote Host and SCP File to Remote Host). A password or key file is required as a parameter value setting.

Additional Information For information about the Pipeline Pilot Integration collection and other BIOVIA software products, visit https://community.3dsbiovia.com.

Page 2 | Pipeline Pilot • Command-line Components Guide Chapter 2: Run Program

You can execute third-party applications from within Pipeline Pilot Client using the Run Program components. They provide a way for you to execute an operating system command on the server or on the client machine. Using these components, you can extend the functionality of a protocol to include any operation that you can invoke from a Windows command line. For example, you can write out one or more data files, invoke the command line program to work on these files, and then read the results when the protocol is completed. The Run Program components include: Run Program (on Client): Runs a third-party Windows application that can be executed using the DOS command prompt on the client machine. Run Program (on Server): Runs a third-party application on the server. You configure parameters in this component that specify how to run the external application.

Using Run Program in Protocols To use the Run Program components in a protocol, you need to configure parameters that specify how to run the external program. The parameters differ slightly for each component. One parameter they both share is WaitForExit; you can run external applications in different modes by setting the following values for this parameter: True (default): Pipeline Pilot runs in blocking mode (the protocol continues after the program is finished running). False: Pipeline Pilot runs in non-blocking mode (the program is launched and Pipeline Pilot continues to run the protocol, even when the program is not finished). Tip: More detailed information about setting all the parameters available in the Run Program components is available in the component reference . For details, open the component in the Pipeline Pilot Client workspace and view the Help text in the lower-left window. To create and run a protocol that uses Run Program: 1. Add the Run Program (on Server) component to your protocol, along with a file writer and file reader component. The file components are optional, but they are frequently included to pass data records to and from the command-line application. In the case of Run Program (on Client), Copy to Server and Copy to Client components are also useful for managing local copies of the data on the client machine.

Run Program | Page 3 Run Program protocol 2. If data records are passed to or from the command-line applications, store the names of the files that hold the data in global variables. Tempfiles are a convenient way to do this, because Pipeline Pilot automatically creates the files and stores the filenames to a global variable. Tip: To encapsulate your file-handling components and Run Program components so they look and act like one component, select all three and choose Collapse to Subprotocol from the right- click menu. 3. Enter the command-line syntax in the CommandLine parameter of Run Program. Enter the text, including options and arguments, just as it would appear if you were typing it the command-line. Example: ":\Program Files\xyz\xyz.exe""$(inputfile)""$(outputfile)"

Tips: Insert the value of global variables into your command-line syntax by surrounding the variable name with parentheses and inserting a dollar-sign beforehand, as in "$(inputfilename)". To keep spaces in the name from causing the command-line interpreter to split the name in two, place filename arguments in quotes, as in "C:\Program Files". This is particularly easy to forget when the filename is stored in a global variable. Insert the value of global variables into your command-line syntax by surrounding the variable name with parentheses and inserting a dollar-sign beforehand, as in "$(inputfilename)". To keep spaces in the directory name from causing the command-line interpreter to split the name in two, place filename arguments in quotes, as in "C:\Program Files". This is particularly easy to forget when the filename is stored in a global variable.

Page 4 | Pipeline Pilot • Command-line Components Guide 4. Configure the following parameters for the Run Program component: WaitForExit: Set to "True" if program output is used in subsequent steps of the protocol. StdInProperty, StdOutProperty, and StdErrProperty: Enter property names to transfer values between a data record in Pipeline Pilot and streaming data in the command interpreter. The result of this process is that a command-line application is executed on the server and the output of the application is available for further processing in the protocol. The process is similar to using the Run Program (on Client) component, with the addition of components to copy files to and from the client machine. Tip: To encapsulate your file-handling components and Run Program components so they look and act like one component, select all three and choose Collapse to Subprotocol from the right-click menu.

Run Program | Page 5 Chapter 3: File Transfer Protocol

File Transfer Protocol (FTP) is used to transfer files over a TCP/IP network (Internet, UNIX, etc.). The Integration collection includes the following components that support FTP: Copy File from Remote Host: Downloads one or more files from a remote machine. Copy File to Remote Host: Uploads one or more files to a remote machine. Since these components use the FTP protocol, a valid user name and password are required as parameter values. Typically, FTP components are used in conjunction with Telnet or SOAP components to run programs on a remote machine.

Running a Protocol with an FTP Component To create and run a protocol that transfers files to a remote machine: 1. Add the Copy File to Remote Host (FTP) component to the protocol.

2. Specify the paths and filename of the file to copy and of the target location.

FTP component parameters 3. Specify the hostname, username, and password for login on the remote machine.

Hostname, Username, Password parameters

File Transfer Protocol | Page 6 4. Press F5. The protocol runs and executes the file transfer. The files are copied from the server to the remote machine. The file can be used in subsequent steps of the protocol, or a transfer at the end of a protocol may serve to publish results.

Page 7 | Pipeline Pilot • Command-line Components Guide Chapter 4: Telnet

Telnet is a terminal emulation method used on the Internet and TCP/IP-based networks. It allows a user to log onto a remote computer and run a program or execute UNIX commands. The Integration collection includes a component that supports Telnet called Run Command on Remote Host (Telnet). It is written in Perl and uses the Net::Telnet package. Required parameters for the component include Username and Password. Typically, this component is used with the FTP components to transfer input and result files to and from the remote host.

Telnet | Page 8 Chapter 5: SCP and SSH

Components are available that support both SSH and SCP, secure methods for accessing servers and transmitting files. SSH and SCP can work independently or together in a protocol to provide integration capabilities. SSH: A security method for logging on to a remote server. It provides an encrypted session for transferring files and executing server programs. SSH supports a variety of authentication methods and it provides a secure client/server connection for applications. SCP: A secure version of the UNIX remote (rcp) command for transmitting files to or from a remote machine. Unlike FTP, SCP encrypts all communication with the remote host. The Integration collection includes the following components for this purpose: SCP File from Remote Host: Downloads one or more files from a remote machine in a format that is encrypted with the remote host. SCP File to Remote Host: Uploads one or more files to a remote machine in a format that is encrypted with the remote host. Manage Trust (SSH/SCP): Validates or updates a key signature in a known host file, which allows you to verify the identity of the remote host before sending the encrypted password. Run Command (SSH): Runs a command on a remote machine running SSH daemon. Note: A password or key file is required as a parameter value setting for the above components.

Running a Protocol with a SCP and SSH Components To create and run a protocol that supports SCP/SSH:

SCP and SSH | Page 9 1. Add the following components in order: 1 SCP File to Remote Host 2 Run Command on Remote Host (SSH) 3 SCP File from Remote Host

2. Configure all of the components with the login information.

Login information for components 3. On the SSH component, enter the command to run on the remote host, just as you would it at the command line.

SSH component parameters 4. Press F5. The protocol runs, data is transferred to the remote host, data is processed using the command specified for SSH, and the results are retrieved.

Page 10 | Pipeline Pilot • Command-line Components Guide