WPS Workbench. user guide. To help guide you through using WPS Workbench to create, edit and run programs. Workbench user guide Version 3.

Transcription

1 WPS Workbench user guide To help guide you through using WPS Workbench to create, edit and run programs Version: Copyright World Programming Limited

2 Contents Introduction...7 About this guide... 7 About WPS...7 Eclipse...8 WPS and SAS software... 9 Getting started...11 Workspace Launcher...11 Welcome pages Migrating existing programs or projects...13 Migrating from previous versions of WPS...13 Migrating from SAS software...13 Importing the sample and other projects Workbench layout...14 Default WPS perspective Online help Cheat sheets WPS components...22 Licence key...24 Applying a licence key Viewing your applied licence details...24 WPS server Configuring the local WPS installation...27 Default WPS server WPS server LOCALE and ENCODING settings General text file encoding Workbench views...32 The Project and File Explorer views...32 Project Explorer File Explorer Link Explorer WPS Server Explorer Local WPS server properties Remote WPS server properties Properties

3 Editor Bookmarks Tasks Outline (of structural elements)...48 Output Explorer Results Explorer Progress...51 Console (for remote server standard output)...52 Search Working with views View stacks Opening a view Closing a view...55 Moving a view Detaching and re-attaching a view Resizing a view Minimising a view...57 Maximising a view Restoring a view Perspectives Opening a perspective Closing a perspective Resetting a perspective...59 Saving a perspective Deleting a perspective...60 Projects Project Definition File Managing projects Creating a new project Copying a project Deleting a project Closing and re-opening a project...68 Importing files Exporting a project Working with multiple projects...71 Switching to a different workspace Local history Comparing with local history Replacing with local history...73 Restoring from local history Local history preferences Comparing and merging multiple files

4 Managing files within the File Explorer Creating a new folder in a file system...77 Creating a new file in a file system Creating a new program file in a file system Opening a file in a file system...79 Moving a file within a file system Moving files using Cut and Paste Moving files using Drag and Drop Copying a file within a file system Copying files using Copy and Paste...80 Copying files using Drag and Drop...81 Renaming an object within a file system Deleting an object from a file system WPS File Explorer Preferences (Hidden Files) Preferences Preferences filter General Preferences Shortcut Key Preferences Backing up your Preferences...87 Creating a new program WPS Syntax Colouring...92 Entering WPS code via templates Dynamic Help for Language Elements Using Program Content Assist...94 WPS Code Injection Code Analyser...95 Analysing program compatibility...96 Analysing language usage Analysing mainframe programs...98 Viewing or exporting an analysis report...99 Analysis restrictions Working with editors SAS Editor Text Editor System Editor In-Place Editor Default Editor Text Editor Preferences Closing files

5 Text-based editing features Bookmark anchors Adding a bookmark Deleting a bookmark Task markers Adding a task Deleting a task Jumping to a particular project location Navigation between multiple project files Searching and replacing Undoing and redoing your edits Libraries Set WORK location Catalogs Datasets Importing datasets Opening a dataset Exporting datasets Clearing datasets Running programs WPS Preferences for running programs Running a program from inside the Workbench Running part of a program Stopping an execution WPS in Command Line mode Running a program from the command line of a Windows platform Running a program from the command line of a non-windows platform Working with program output Dataset generation Managing ODS output Result Options Preferences Logs PDF output Listing output HTML output Clearing the results output Restarting the server WPS Link client/server setup Managing local and remote host connections

6 Local host connection properties (Directory Shortcuts) Creating a new remote host connection Defining a new WPS server Exporting host connection definitions to a file Importing host connection definitions from a file Exporting WPS server definitions to a file Importing WPS server definitions from a file Database connectivity Introduction Connecting to an Oracle database Connecting to a DB2 database Connecting to a SQL Server database Connecting to a MySQL database Connecting to a database using ODBC Configuration files AutoExec file WPS Tips and Tricks Troubleshooting Making technical support requests Legal Notices

7 Introduction About this guide This user guide is intended to help you gain familiarity with the graphical user interface of WPS (the World Programming System), which allows you to create, edit and run programs written in the SAS language (hereafter referred to as SAS programs). This interface is referred to as WPS Workbench, or, more simply, the Workbench. The user guide also covers the running of SAS programs using WPS in Command Line mode, and various system administration features. The user guide has a WPS Tips and Tricks section that provides you with links to some useful features, and a Troubleshooting section to help you resolve some problems that users have previously reported. The user guide does not aim to: Train you in the use of the SAS language. If you are not already familiar with this language, there is a wide range of educational and reference material available from many sources. Teach you every option within WPS. However, once you have worked through this guide you should be sufficiently familiar with the system to run some basic programs and to begin processing and analysing data. Notation Whenever you need to type in code, the guide displays it like this: PROC OPTIONS; RUN; In general, the guide uses menu options when suggesting that you need to interact with WPS, but there are also toolbar buttons and context menu options available for many WPS options. Menu and button options are shown in a bold font, for example File New Project. About WPS The World Programming System (WPS) consists of two fundamental components: 7

8 A GUI (Graphical User Interface)/IDE (Integrated Development Environment) known as WPS Workbench. This environment utilises the Eclipse platform as the basic framework to provide the GUI. This GUI/IDE provides facilities to manage, create and edit programs written in the SAS language, and then to run these programs via the WPS server. A compiler/interpreter. This can be run from the command line (CLI) and is used to execute existing programs (sometimes referred to as running WPS in batch mode). When using WPS Workbench, the compiler is run as a server process (refer to WPS server process below) and is used to process and execute programs. WPS server process In order to run programs written in the SAS language (refer to WPS and SAS software), WPS Workbench requires a connection to a WPS server process (for more information, refer to WPS server). This process may be running either on the local workstation (a local host connection), or on an installation of WPS on a remote machine (a remote host connection). Servers running under the local connection are termed local servers, whilst servers running under a remote connection are termed remote servers. WPS licence key(s) In order to be able to execute a program written in the SAS language, the WPS server component needs to be activated by the application of a WPS licence key (supplied separately). Refer to the section on the Licence key. Important: The person who installs WPS and applies the licence keys on a machine must have operating system administrator privileges on that machine. Eclipse Eclipse is an open source tool originally developed by IBM. It provides an environment for editing and managing files and tasks. It is designed to accommodate plug-ins to perform specific tasks, such as XML editing, Java Development, source control, and so on. WPS Workbench is an example of the Eclipse environment supplied with a suite of plug-ins suitable for editing SAS programs. WPS intentionally leaves the Eclipse environment open for advanced users to plug in other third party tools and facilities for source control, Java development, C++ development, XML editing, and a variety of other uses. Because the Eclipse platform can accommodate other plug-ins, WPS Workbench has some features that it does not presently utilise but they are included to allow users to add other Eclipsebased plug-ins and extensions. 8

9 Some of the features mentioned in this guide are actually built-in features of Eclipse, but are referred to as features of WPS for simplicity. WPS not only inherits functionality from Eclipse but also has specially designed features and controls to aid program development and use. For more information about Eclipse and other available plug-ins, visit Eclipse features not used by WPS Under the Project menu, none of the Build or Clean menu items are used by WPS. Help Check for Updates does not retrieve updates for the WPS software. This menu item only retrieves updates to the Eclipse platform itself, or other new or updated third party plug-ins. WPS and SAS software If you are accustomed to using other products related to the SAS language, you will find that the language support in WPS is familiar. You can expect to find much of the same syntax in terms of procedures, formats, macros, DATA steps, and so on. WPS will also provide other recognisable features and objects such as logs, datasets, Work library, and so on. Other features may be new to you, such as the Workbench environment itself and the way in which it handles or displays objects. You will find that the Workbench has help and reference material to assist you in migrating to WPS. Compatibility with SAS software Besides being able to run, modify, share and save programs written in the SAS language, WPS is also able to read from and write to data files used by SAS software. WPS also includes a wide selection of library engines to allow you to access many leading third party databases, data warehouses and Hadoop big data environments. WPS also uses a proprietary dataset file format known as WPD. As the default dataset library engine, WPD datasets are used for the Work library. Because it is the dataset library engine that is native to WPS, it has the most complete feature support, including, for example, indices. Supported language elements WPS does not yet support every element in the SAS language. The Workbench provides a Code Analyser to help determine if any of your existing SAS programs contain unknown or unsupported language elements. Refer to the help guide entitled WPS Reference for Language Elements for details on the syntax of the language elements that are supported. 9

10 Existing SAS programs WPS uses the term SAS program, or simply program, to describe scripts, programs and applications written in the SAS language. To use existing programs within WPS Workbench, refer to Migrating from SAS software. 10

11 Getting started Workspace Launcher WPS Workbench is launched via \eclipse\workbench.exe in your WPS installation, or via the associated shortcut. When you first launch WPS Workbench, the Workspace Launcher is displayed, for example: A workspace is the parent folder used to hold one or more projects. It is possible to use any folder on any drive that your computer can access, as a workspace. The workspace must have a physical location, which is also the default location for the newly created projects within it. However, projects can be created in non-default locations. From version 3.1 of WPS onwards, it is no longer a requirement to use projects to manage your Workbench resources. This is because many files accessible through the operating system are now available from within the Workbench, via the File Explorer. You can also make connections to other, remote computers in order to access files stored elsewhere (refer to the Link Explorer). On Windows, the default location of the workspaces when WPS is first installed is your My Documents folder, and, on UNIX and Linux platforms, it is the directory to which your $HOME environment variable is set. In all cases, the sub-directory is called WPS Workspaces and the workspaces are named incrementally, starting at Workspace1. 11

12 If you do not wish to use the workspace folder that is suggested in the Workspace field, then either click the drop-down to the right of the field to select an alternative workspace, or click Browse to bring up the Select Workspace Directory dialog (this allows you to either select an existing folder to use as a workspace, or create a new folder). Whenever you change the line in the Workspace field of the Workspace Launcher to point at a new workspace, then the Welcome pages are redisplayed. Unless you select Use this as the default and do not ask again, then the Workspace Launcher will re-appear whenever you launch another WPS Workbench session. If you do select this option, you can always redisplay the Workspace Launcher subsequently by selecting Window Preferences General Startup and Shutdown Workspaces Prompt for workspace on startup. Welcome pages The Welcome pages display introductory information about WPS Workbench. The default Get Started page is designed to help you start using WPS Workbench as quickly as possible. This page also displays a number of links to other welcome pages, including our website. Closing and re-opening the welcome pages To close the welcome pages and start using the Workbench without further guidance, click the button on the Welcome tab. You can re-open them at any time by selecting the Help Close Welcome. Other controls Located near the top right of the welcome pages are some navigation and size control buttons: Navigation buttons: These behave much like the buttons on a normal web browser: Home: Go to the start page. Navigate to previous topic: Go backwards to a previously viewed topic. Navigate to next topic: Go forwards to a previously viewed topic. Size control buttons: These change the size of the welcome pages within WPS Workbench: Minimize: Shrink the welcome pages to their minimum size. This will reveal other windows that are open. Restore: Make the welcome pages go back to a normal docked view alongside the other open windows. Maximize: Expand the welcome pages to fit the entire Workbench and hide any other open windows. 12

13 Migrating existing programs or projects This section of the guide is aimed specifically at users who have existing Projects or programs created using either software from the SAS Institute Inc. or earlier versions of WPS, and who wish to use these existing objects with the latest version of WPS. Migrating from previous versions of WPS Workspaces opened with previous versions of WPS can be opened with the current version, so there are no migration steps to be performed to use a workspace from a previous version of WPS with the latest version. However, the first time that you open a workspace that was created using an earlier version of WPS, an Eclipse dialog is displayed asking for your confirmation that it is OK for the workspace to be upgraded automatically. Such automatic upgrades should not cause any problems. Existing programs do not need to be modified to work with the latest version of WPS. In addition, projects that were created with earlier versions of WPS can be opened and used by later versions of WPS without any additional action. Migrating from SAS software If you already have programs written in the SAS language, there is no conversion process to undertake in order to use these programs with WPS. Any file with the extension.sas is assumed to be a program that the Workbench can open, edit and run. Accessing your existing programs You can access your existing programs from the File Explorer. Alternatively, you may wish to work with projects through the Project Explorer, which allows you some benefits, for example Restoring from local history, that are not available with the File Explorer. For help on how to manage your existing program files, refer to The Project and File Explorer views. Checking program compatibility Opening programs in the Workbench causes unknown or unsupported language elements to be displayed in red. However, before trying to execute your existing programs in WPS, it is also recommended that you use the Workbench Code Analyser for further verification. Analysing programs, even hundreds of programs at a time, can take less than a few minutes to complete and can therefore be quicker than trying to execute long-running programs only to find that some changes may be required. Program analysis is available from both the File Explorer and Project Explorer. 13

14 Caution: Although it is generally very accurate, the Code Analyser is not guaranteed to be 100% accurate owing to the nature of the syntax of the SAS language. Importing the sample and other projects To import an existing project into the Workbench: 1. Launch the Import wizard by selecting File Import. You will see the first page of the Import wizard. 2. Expand the tree under the 3. Highlight the General node. Existing Projects into Workspace option. 4. Click Next >. 5. Select one of the following options: Select root directory: Use this if the project is not archived in a single file. Click Browse... to select the folder where the project is located. Select archive file: Use this if the project to import is archived in a single file (as a zip, tar or tar.gz, for example). Click Browse... to select the archive file containing the project. If you wish to select the sample projects that were supplied with your version of the Workbench, browse to the doc folder within your Workbench installation, select your language folder (for example, en, es or fr), and then select the relevant samples.zip folder. If the file or folder you just browsed for contains a valid project, you will see it listed in the Projects section of this panel. All projects that are initially listed are selected for import by default. Deselect any of those that you do not wish to import. 6. Click Finish to start the import process. Workbench layout The layout of the Workbench can be changed according to your needs. The various layouts are known as Perspectives, with each different perspective being specifically intended for the task of creating, managing, editing and running particular programs. 14

15 Default WPS perspective The following is an example of the default WPS perspective used immediately following the initial installation of WPS Workbench: The default WPS perspective shows all Workbench views, with the exception of Online help, Bookmarks, Tasks and Search. If you need to return to this perspective at any time, select Window Open Perspective WPS. Although you cannot delete or rename this WPS perspective, you can save your own screen layout under the same name. Refer to Perspectives for details on customising this layout. 15

16 Online help The context-sensitive Help view allows you to display relevant help items automatically as you select different Workbench views. This view is not open by default. To add this view to the current perspective, press F1 on your keyboard, or select either Help Dynamic Help or Window Show View Other Help Help. This help will update dynamically as you select different views around the interface. However, once you have navigated away from a dynamic help page, for example by clicking the Related Topics at the top of the Help view, then the help will no longer dynamically update as you move around the user interface. To restore the context-sensitive help, either press F1 again or click the Related Topics link. If you wish to display the contents of the full WPS documentation in an Eclipse help tree view outside the Workbench, select Help Help Contents. You can also access this same window by selecting Show in External Window from the Help view toolbar (although selecting this option opens the Eclipse help at the current Workbench topic). This external view is not context-sensitive. Help view controls As you navigate by clicking on the various links and buttons in this Help view, you will see numerous different controls available, for example: Related Topics: If this link is bold, then it indicates that the help is currently context-sensitive. If you click on any of the related links below it, then the Related Topics link is no longer bold, which indicates that you need to either press F1 or click the Related Topics link again to restore context-sensitivity. Show in Contents: This will synchronise the help topic you are looking at with its position in the contents tree view. Bookmark Document: You can add a bookmark to any help page so you can navigate immediately to that topic again. All your bookmarks are listed via the Bookmarks link in the Help view. Search: Use this facility to search the help for specific keywords and phrases. List of key bindings If you wish to view the list of key bindings (that is to say, current keyboard shortcuts), either select Help Key Assist or press Ctrl + Shift + L. To display the Preferences page on which you can change the key bindings, or add new ones, you can then either press Ctrl + Shift + L again, or select Window Preferences General Keys. Refer to Shortcut Key Preferences. 16

17 Cheat sheets The Workbench is supplied with tutorials known as cheat sheets. They are designed to help you start using WPS by introducing you to specific tasks and features. A cheat sheet is laid out as a sequence of steps for you to undertake. As you progress from one step to the next, the cheat sheet has a Help button that you can select to display a related help topic that discusses or guides you through that particular step. Cheat sheet types Cheat sheets can be one of two different types: A simple or composite. simple cheat sheet is a list of tasks designed to be performed one after another. It has an introduction to set the scene, and then a number of tasks that follow on, as shown below: These cheat sheets appear as a simple list in the Workbench user interface. A composite cheat sheet is really just a collection of simple cheat sheets. They break down a large complicated topic, made up of many tasks, into smaller manageable groups. Each of these groups has its own introduction and conclusion, as shown below: Composite cheat sheets have two panes in the user interface. One shows the groups of tasks, whilst the other allows you to work through the tasks in each group. 17

18 By default, the groups pane is above the tasks, although maximising the view will move it to the left. Launching a cheat sheet Cheat sheets can be launched either from the welcome pages or from the Workbench main menu. Launching a cheat sheet from the welcome pages: 1. Open the welcome pages by selecting Help Welcome. 2. Select the Tutorials page. 18

19 3. From the list of available cheat sheets, click on the one you wish to open. Launching a cheat sheet from the Workbench Menu: 1. From the main menu, select Help Cheat Sheets From the list of available cheat sheets, double-click on the one you wish to open. Cheat sheet quick toolbar If you launch a cheat sheet from the Workbench menu (as opposed to from the welcome pages), a toolbar is displayed specifically for use with the cheat sheet: Collapses all the expanded steps except the current step, or expands steps to the last expanded state. Click to toggle between these two states. Allows you to select and open another cheat sheet. If there is already an active cheat sheet, its completion status is automatically saved and then the newly selected cheat sheet is opened. Only one cheat sheet may be open at any one time. Minimize the cheat sheet view. Maximize the cheat sheet view. This button is in the tab of the cheat sheet view, and, as well as closing the view, it saves the status of the active cheat sheet so that your position is not lost. Working through a cheat sheet Each cheat sheet has a sequence of steps that always begins with an introductory step. When you launch a new cheat sheet, the introductory step is expanded so that you can read a brief description about the selected cheat sheet. To start working with a simple cheat sheet, select Click to Begin at the bottom of the introductory step. The next step is then expanded and highlighted. You should also see action buttons at the bottom of the next step, for example Click to Complete. You can now progress through each step in the cheat sheet. To start working with a composite cheat sheet, read the introduction and then click the Go to... link at the bottom of the first sheet. The introduction for the first group of tasks will be displayed, and you can then click on the Start working... link to begin. From this point on, the task group behaves very much as a simple cheat sheet. Completing a cheat sheet With simple cheat sheets, when you have finished working with a particular step, you should select Click when complete to move to the next step. The next step is automatically highlighted and it becomes the active step. A check mark appears in the left margin of each completed step. 19

20 Composite cheat sheets behave in much the same way, until you complete all the sheets in the current group. Composite cheat sheets have a conclusion, and also the option to review the task, or to progress onto the next group of tasks (by clicking on the 'Go to' link). Starting the next task will take you to the introduction for the next group. Getting Related Help information To obtain detailed instructions or related information for a particular step, select the Open Related Help icon in the upper right hand corner of that step. The Related Help will open in a separate Help window. Open any step You can open any step out of sequence, regardless of whether it is selecting it via its icon. marked as completed, by simply Any step opened in this way will not change from its complete or incomplete state, and steps following the active step do not have a Click to Complete icon. Click Collapse All Items but Current at the top of the cheat sheet view to collapse back to just the current active step waiting to be completed. In composite cheat sheets, you may go back to any task group to review it by simply clicking on the group in the task group pane. You will be placed back to wherever you were when you left that group last, so if you completed it, you will be able to see the conclusion. You may not, however, start another task group until you have completed the tasks in the proceeding groups. Restarting a cheat sheet At any time you can restart from the first step. To do this, first open the first step (Introduction) by clicking on its expand icon and then select the Click to Restart icon at the bottom of that step. Any objects (for example, programs, projects, and so on) that you have already created, are not deleted when you restart a cheat sheet. Composite cheat sheets allow you reset task groups. Right-click on the task group in the groups pane, then select Reset from the menu. You will then see a confirmation dialog. Click OK and the introduction for the group is then shown in the task pane. Completing a cheat sheet With simple cheat sheets, when you finish the last step, it automatically goes back to the first step (Introduction). You can either click on the first step's Click to Restart icon or just close the cheat sheet. 20

21 Composite cheat sheets are considered complete when all task groups have been completed. If this is the case, then all groups will have a check mark next to them in the groups pane. You may then restart all the task groups if you wish, by right-clicking the top level item in the groups pane and selecting Restart all tasks. Closing a cheat sheet You can close the active cheat sheet by selecting the Close icon in the cheat sheet's tab. The active cheat sheet saves its completion status when it is closed so that you can continue where you left off when you next re-open it. 21

22 WPS components This section gives brief descriptions of the objects managed by the Workbench. Projects These consitute the fundamental unit of organisation. You would typically put related programs together in a project. For example, you might have a project for applications under development, another for monthly reporting jobs, and so on. Programs You can create and modify programs, that is to say files with the extension of either.sas or.wps, using the SAS Editor (refer to Creating a new program for an example). This editor uses colour coding to highlight different language elements as well as syntax errors. Logs When you run a program inside the Workbench, the information generated is stored in the log file. This file can be viewed, printed and saved from within the Workbench. The log generated by WPS is cumulative and contains the results of each program that has been run since WPS Workbench was launched, the WPS Server was last restarted, or the log was last cleared. Listing output This contains the printed output from any programs that you have run. For example, this could be a table of data generated by a PROC PRINT statement in a program. Listing output can be viewed, printed and saved from within the Workbench. The listing output generated by the WPS server is cumulative and contains the output from each program that has been run since the Workbench was launched, the WPS server was last restarted, or the listing was last cleared. HTML output These are the physical HTML files that a program may generate. For example, they could be a series of HTML files that show the results of analysing some data, and that have been generated as a result of an ODS HTML statement in a program. HTML output can be opened and viewed within the Workbench. ODS output (refer to Managing ODS output) As described, the ODS (Output Delivery System) can be used to produce text listing and HTML output. Each program can specify when and where its output is stored but it is also possible to allow the Workbench to manage the process automatically. The default option is for the Workbench to generate HTML output for viewing via the Output Explorer. Libraries These hold the temporary files, datasets, catalogs, and so on, that are created as a result of running a program. Filerefs (refer to WPS Server Explorer) These hold the individual references to files, whether automatically generated or defined via the FILENAME statement. 22

23 Datasets The data generated from running a program is stored in datasets. You can either browse or edit a dataset using the dataset viewer. Host Connection This refers to a computer, local or remote, to which the Workbench has access. The creation of a host connection is the first step of a two-step operation to create a remote link inside WPS: you first create a connection to the remote host; and then add a WPS server to this remote host so that you can run your programs remotely (refer to Managing local and remote host connections). WPS server This is the engine responsible for executing programs and generating the resulting output, such as the log, listing output, HTML results files, and datasets. A WPS server is associated with a particular host connection. The WPS server also maintains an environment of assigned libraries, Filerefs, defined macros and macro variables, and so on, with which all of the running programs interact. Directory Shortcut A Directory Shortcut is a shortcut to a path on the host's file system that can be accessed via the File Explorer (refer as appropriate to Local host connection properties (Directory Shortcuts) or, for a remote host, Directory Shortcuts). You can create new directory shortcuts via the relevant host connection's Properties in the Link Explorer, or by right-clicking on the required folder(s) in the File Explorer and selecting New Directory Shortcut. 23

24 Licence key WPS requires a valid licence key in order to run programs on a WPS server. A licence key is provided in a file ending in.wpskey that is separate from the WPS installation file. If you are using WPS Link (refer to the Link Explorer), and wish to restrict the execution of programs to the linked server, then you only need a licence key for the server installation of WPS. However, if you wish to be able to execute programs on either the client machine or the linked server, then you need separate licence keys for the server and the client installations of WPS. Applying a licence key To apply a new licence key to your WPS installation. Attention: If you are using a Microsoft Windows operating system, then, before applying a licence key, ensure that you have administrator privileges on your computer. 1. Select Help Apply Licence from the Workbench menu. 2. In the resultant dialog Import licence for server Local Server (or substitute the name of your remote WPS server in place of Local Server), do one of the following: Copy and paste the entire contents of your licence file into the window. Click Import from file... Locate your licence key file and then click Open. You should see the contents of the licence key file displayed in the window. 3. Click Finish to apply the licence. If you wish to apply the licence key on a Unix-based platform, then enter the following: wps_install_root/bin/wps -stdio -setinit <license.wpskey wps_install_root is the directory where WPS is installed. Viewing your applied licence details To view the details of the licence key that has been applied to your WPS installation: 1. Open the Licence Key information window by selecting Help Workbench menu. 24 View Licence from the

25 2. Click OK when you are ready to close the window. 25

26 WPS server In order to run programs, the Workbench requires a connection to a licensed WPS server. The term server here is used to refer to a server process. The process may be running on the local workstation (as a local host connection - refer to Local host connection properties (Directory Shortcuts)), or it may be running on an installation of WPS on a remote machine (as a remote host connection - refer to Remote host connection properties). Servers running under the local connection are termed local servers. Servers running under a remote connection are termed remote servers. With a typical workstation installation of WPS there will be a single host connection called Local and a server called Local Server. This server will be started by default when the Workbench is started, and terminate when the Workbench is closed down. Further local servers can be created if required or the local server can be deleted or uninstalled (refer to Configuring the local WPS installation). If you are using a non-windows platform, and wish to run programs on a remote server only, then you can go into the Link Explorer in WPS Workbench and either Stop or Delete the Local Server, without your licence being affected. However, deleting all local servers, where there are no remote servers, will render users unable to run programs. Creating multiple local servers requires no further licensed WPS products and the only restriction on the number of local servers that can be created is the local machine resources. One reason that you might want to create multiple local server connections is to configure them with different startup options, for example different values of LOCALE or ENCODING. Setting up remote servers gives you the ease of use of the Workbench at your local workstation, while also giving you access to the processing power of remote server machines. Multiple servers can run under a single remote host connection. Creating a link to a remote host, so that you can run your programs remotely, is a two-step operation: 1. Create a connection to the host by following the steps in Creating a new remote host connection. 2. Define a server on this host by following the steps in Defining a new WPS server. Once a connection to a remote machine has been authenticated, one or more WPS servers can be started without the need for further user authentication. Multiple users can have remote connections configured to the same machine, with the only restriction being the resources on that machine. The list of defined connections and servers is stored within the workspace, and is maintained via the Link Explorer. Therefore, changing your workspace will potentially load a list of different connections and servers. When you create a new workspace, then, by default, there is a single host connection called Local and a single server called Local Server. 26

27 For user convenience when moving between workspaces, or to share server definitions within a work group, server definitions can be exported to an external file (see Exporting WPS server definitions to a file) and imported from a file previously created in such a way (see Importing WPS server definitions from a file). Configuring the local WPS installation Because it is not mandatory to use the WPS server component on the local host if programs are not being executed on it (in that they are being run only on a remote linked server), you can isolate the WPS Local Server from the installation as described below. You can only do this on a workstation that is running on Windows. If you have not already installed WPS, then run the relevant wps msi, and, when the following Custom Setup screen is displayed, deselect WPS Local Server, as shown below, before going on to click Next: If you have already installed WPS, then select WPS from the Programs and Features within the Windows Control Panel, click Change at the top of the window, followed by Change again in the following window: 27

28 You will then come to the Custom Setup shown previously and can deselect WPS Local Server as shown, before completing the amended installation. Caution: You should be aware that, if you uninstall WPS Local Server from a machine, your WPS installation will no longer be licensed on that machine. If you are using a non-windows platform, and wish to run programs on a remote server only, then you can go into Link Explorer and either Stop or Delete the Local Server, without your licence being affected. Default WPS server One of the defined servers is always set as the default server. This is the server that is selected by default when you click on any of the following toolbar icons, or their associated keyboard shortcuts: Run, Stop, Clear Log, Clear Results and Restart Server. Proceed as follows to set the default server. 1. Go to the WPS Server Explorer, Link Explorer, Output Explorer or Results Explorer, and right-click on the server that you wish to be the default. 2. From the context menu, select Set as Default Server. 28

29 If this option is not enabled, then the selected server is already the default server, or you have selected more than one server. The selected server is now the default WPS server, and, to denote this, it appears first in the list of servers and is shown in bold. WPS server LOCALE and ENCODING settings The locale used by WPS is set individually by the particular server. Proceed as follows to set the language system option for the locale that you wish to use for a server: 1. In the WPS Server Explorer, Link Explorer, Output Explorer or Results Explorer, ensure that the server is running. 2. Right-click on the server and select Properties from the context menu. 3. In the left hand menu of the Properties dialog, select Startup System Options. 4. On the right of the window, click Add... to display the Startup Option dialog. 5. Click Select... on the right of dialog to see a list of available options in a Select Startup Option window. 6. Search for and/or scroll down to the LOCALE option, and then double-click on it. The Startup Option dialog then displays your choice. 7. Enter the required value into the Value text box, and then click OK. A list of valid LOCALE values can be found in the separate guide entitled WPS Reference for Language Elements, in the LOCALE Values section. 8. Click OK on the Properties dialog and you will be prompted to restart the server to apply your changes. Any LOCALE option defined in any external Configuration files will be ignored. You must set LOCALE as a Workbench startup option, as described above, in order for it to be used from inside the graphical user interface. However, when using WPS in Command Line mode to run programs in batch mode, then the startup option is ignored and the LOCALE option in the external configuration file is used instead. In order to display and save programs and other files that contain characters for your selected LOCALE, you may need to set a General text file encoding value for the Workbench. 29

30 You may also need to set an appropriate ENCODING value on the server (for example to execute a WPS installation containing non-ascii characters). As an example, proceed as follows to set UTF-8 on the server: 1. Repeat steps 1-5 as above. 2. Scroll down and double-click on the ENCODING option, which will be displayed in the Startup Option dialog. 3. Enter UTF8 or UTF-8 into the Value text box, and then click OK. 4. Restart the server when prompted. A list of valid ENCODING values can be found in the separate guide entitled WPS Reference for Language Elements, in the ENCODING Values section. General text file encoding In order to display and save programs and files that contain international characters, you may need to set an appropriate text file encoding value. This can be done at either a global or project level. Setting encoding at a global level To set an encoding value at a global level to be used by all projects and associated files: 1. Select Window Preferences. 2. In the left hand menu of the Preferences window, expand the General Workspace node. 3. In the bottom left of the Workspace panel, the controls for setting the Text File Encoding value are displayed. 4. Enable the Other option for Text File Encoding and select the required value from the drop-down list of available values. 5. Click OK to apply your change. You can type in the required encoding in the Other field if you do not see the required option in the drop-down list. If your selection is valid, it is saved when you click OK. It is recommended that, in all cases, you check that the locale is set for your country so that data is handled correctly by the WPS server. To do this, ensure that the server is started and that the locale displayed in the bottom right hand corner of the Workbench is set appropriately (for example, to FRENCH_FRANCE or FR_FR if you are in French territories). If it is not, proceed as in WPS server LOCALE and ENCODING settings. 30

31 Setting encoding at a project level To set an encoding value only for programs contained in a specific project: 1. Ensure that you have the Explorer). 2. Highlight the desired Project Explorer open (Window Show View Project project. 3. Select File Properties. 4. On the left of the Properties window, ensure the Resource option is selected. 5. In the bottom left of the Resource panel, the controls for setting the Text File Encoding value are displayed. The default option selected is Inherited from container(x), where (x) is the value set at a global level as described above. If you wish to change this, enable the Other option for Text File Encoding and select the required value from the drop-down list of available values. 6. Click OK to apply your change. 31

32 Workbench views The layout of the items in WPS Workbench is known as a perspective (refer to Perspectives) and comprises individual windows that can contain one or more views. These views display specific types of information and provide specific functions. Some views also have context-specific toolbars located in the top right of each view. This section gives an overview of each of the views that is available for selection (other than the Online help, which has already been covered) and describes the main actions that are carried out within each view. Views are usually selected via Window Show View. However, where a view has not been previously selected, you may need to locate it initially under Window Show View Other... The Project and File Explorer views Both the Project Explorer and File Explorer views allow you to edit and manage files and folders in a tree structure within the Workbench: 32

33 The Project Explorer is ideal where you have a set of files that you need to manage in one organised workspace. You can create several Projects in a workspace to tackle different specific tasks. Any kind of local file can be contained in a workspace, and all the operations you would expect to be able to perform on files are available (including the ability to run programs). Objects within projects can be managed with Local history, and they can also be exported to archives or to other folders in the local file system. Such archives can also be imported into this view. The File Explorer differs from the Project Explorer in that it permits access to all files that are available on your local file system, and on any file systems made available by any remote hosts. It also makes use of Directory Shortcuts which can point to folders at any level within the file system on which they are created (refer as appropriate to Local host connection properties (Directory Shortcuts) or, for a remote host, Directory Shortcuts). Local history is not available when using File Explorer, and neither is Import nor files and folders can be moved between file systems by using copy/cut/paste. Export, but The differences can be summarised in the following table showing the availability of the various file operations in both views: Option Project Explorer File Explorer Open and Edit Yes Yes File Management Yes Yes Run Programs Yes Yes Local History Yes No Import and Export Projects and Archives Yes No Manage Remote File Systems No Yes Manage Full Local File System No Yes A program can be run from either the Project Explorer and File Explorer by selecting it, right-clicking, and selecting Run On from the context menu. The menu will then expand to show the list of servers on which the program can be executed. Choosing a server will then run the program on that server. For more information, and alternative ways of running programs, refer to Running a program from inside the Workbench. Project Explorer To display this view To add this view to the current perspective, select Window Show View 33 Project Explorer.

34 The files and folders displayed The main file and folder objects displayed are as follows: Open projects Closed projects Folders Programs (that is to say, any file with the extension.sas or.wps) Other files (text or unknown file extensions) Any type of file can be added to a project and listed by the Project Explorer. If your computer system recognises the file type, then the appropriate icon is displayed. The Project Explorer only displays projects that are in your current workspace. Operating system tools As well as the Workbench's tools, you can use those supplied by your operating system to delete, cut, copy and paste objects into a project. You may need to refresh the Project Explorer to ensure that objects manipulated in this way are displayed correctly (right-click on the project and, from the context menu, select Refresh). If you do use the operating system tools instead of those in the Workbench, you will not have the benefits provided by Local history. Properties Selecting an item in the view. Project Explorer displays information about that item in the Properties The following Properties are shown for shortcuts, files and folders: Modified date & time. The Linked field, which is True if the currently selected file is linked to a file in the associated file system. Name of the item. Size of files (directory sizes are not shown) Path details 34

35 File Explorer To display this view To add this view to the current perspective, select Window Show View File Explorer. File Explorer objects File Explorer are as follows: The main file and folder objects displayed by the Connections: The root node that represents a connection to a host machine. This can be either local or remote. Shortcuts: A directory on a file system selected for management via the Folder: A sub-folder. Programs: Any file with the extension.sas or.wps. Other Files: Text or unknown file extensions. Symbolic linked file: A file that points to another file in the host file system via a symbolic link. Symbolic linked directory: A file that points to another directory in the host file system via a File Explorer. symbolic link. Failed link: A link that points to a file or directory that does not exist. Files are shown with an icon appropriate to the file type, governed by the operating system, where available. The File Explorer only displays connections that are open. Working with connections and shortcuts It is only possible to view files on remote systems when you have an open host connection. Such connections can be opened from Link Explorer, and connections are also opened when starting WPS servers in the WPS Server Explorer. When a host connection is opened, then the appear in the File Explorer. Closing a connection will then remove its node from the same view. Each host connection is configured to have several connection in the Connection will Directory Shortcuts displayed below the File Explorer. These permit access to the files and folders on the associated file system (refer as appropriate to Local host connection properties (Directory Shortcuts) or, for a remote host, Directory Shortcuts). 35

36 Tip: To create a new directory shortcut in the File Explorer, right-click on the required folder, select New Directory Shortcut, and then supply the required shortcut name in the Directory Name field of the Directory Shortcut dialog. Host connections expand into the associated shortcuts are shown with an Directory Shortcuts in the File Explorer. Invalid Invalid Shortcut icon. This means that the path configured for these shortcuts is not available on the file system for that connection. Properties File Explorer displays information about that item Selecting an item (other than a connection) in the in the Properties view. The properties differ depending on whether you are using local or remote connections. The following Properties are shown for shortcuts, files and folders: Modified date & time. Name of the item. Size of files (directory sizes are not shown) Path details The Is Link field, which is Yes if the currently selected item is a symbolic link. Link details (if the item is a symbolic link, such as the link path). On a remote host, the following properties are also available. Accessed date and time. Group and user IDs. Permissions Working with files and folders It is possible to perform the following operations on files and folders within the File Explorer: New: Create a new directory shortcut, directory or file. Cut: Selected files and directories will be moved if the user uses Paste. Copy: Selected files and directories will be copied if the user uses Paste. Paste: Performs a Copy or Cut operation. Delete: Deletes all selected files and directories. Run On: Runs selected programs on a WPS server. Refresh: Refreshes the currently selected node. 36

37 Rename: Renames the currently selected file or directory. Analyse: Analyses the contents of programs, and folders containing programs (refer to Code Analyser). These options are available from the context menu within the File Explorer. With the exception of Analyse, they are also available from the main menu. Progress Progress of the current File Explorer operation can be seen in the Progress view. Link Explorer The Link Explorer allows you to manage host connections, and also any WPS servers on those connections. This is the key view if you are using WPS Link (which is the collective term for the technology used to provide a client/server facility - refer to WPS Link client/server setup). Using WPS Workbench on your local PC (the client), you can connect to a remote server on which WPS is installed, in order to run programs written in the SAS language, on that remote server. The process has two stages: 1. Creating a new remote host connection. 2. Defining a new WPS server. The output from the remote server can then be viewed and manipulated from inside WPS Workbench, just as if the work had been executed locally - for example, datasets and Filerefs through the Server Explorer, the log and other results through the through the Results Explorer. WPS Output Explorer, and links to the results To display this view To add this view to the current perspective, select Window Show View Link Explorer. Objects displayed There are only two node types visible in this view: Connection node: The root node that represents a connection to a host machine. One or more servers can be running on a connection. The connection can either be a local connection or a connection to a remote machine. There can only be one local connection, but many remote connections. Server node: This node represents the WPS installation where you are running your programs. 37

38 Managing the connections and servers If you right-click on an open connection, the following options are displayed: With regard to the above options: If you select Close Connection, then you will also stop the server(s) running on it. You can then either select Open Connection to re-open it, or simply restart the server(s). For details on Export Host Connection, refer to Exporting host connection definitions to a file. To define a New WPS Server, proceed as in Defining a new WPS server. For Import WPS Server Definition, refer to Importing WPS server definitions from a file. Tip: Servers can also be imported by dragging Server Definition Files (with the suffix *.sdx) onto a Connection node in the Link Explorer. If you right-click on a server that is running, the following options are displayed: 38 Host

39 With regard to the above options: If you select Stop, then the server will cease to run any program(s), but the connection will remain open. You will need to select Start to relaunch the server (which will also restart the connection automatically). For details on Restart, refer to Restarting the server and Restarting with Advanced Server Actions. For Set as Default Server, refer to Default WPS server. For Export WPS Server Definition, refer to Exporting WPS server definitions to a file. Properties Right-click on a connection or server in the Link Explorer, and, from the context menu, select the Properties option (if enabled), to gain access to the following: Host Connection properties, consisting of: Directory Shortcuts: Refer as appropriate to Local host connection properties (Directory Shortcuts) or, for a remote host, Directory Shortcuts. Remote Connection Options WPS server properties - refer as appropriate to Local WPS server properties or Remote WPS server properties. Tip: You can also view properties about a server in the Properties view. The server properties include the server version, and the following information about the licence: Expiry DATE, Grace Period, Licensed Operating System, and Licence Number. 39

40 Commands (in the top right hand corner of the window) Collapse All: Collapse the view to show just the root nodes. Create a new remote host connection: Add a new remote connection. Refer to Creating a new remote host connection. Import a host connection definition: Import a connection definition file. For further information on importing connections, refer to Importing host connection definitions from a file. Tip: Host connections can also be imported by dragging Connection Definition Files (with the suffix *.cdx) onto the Link Explorer view. Dragging and dropping a WPS server A WPS server can be dragged and dropped onto a different host connection. A simple drag and drop operation on a WPS server will move the server from its current host connection to the target host connection. Holding down the Control key while dragging will copy the WPS server. To maintain unique names, the copied server will be renamed automatically. You can rename the server manually by rightclicking the server and selecting Rename from the context menu. WPS Server Explorer For each active server, the following are displayed in, and, can be opened from, the WPS Server Explorer: all Filerefs, libraries, catalogs and datasets that have been generated as a result of running programs on that server, for example: 40

41 While the Workbench is open, the Filerefs and library contents from previous runs are preserved. In order to clear the state of a server, you need to restart the server (as described in Restarting the server). To display this view To add this view to the current perspective, select Window Show View WPS Server Explorer. Objects displayed Assuming that you have run one or more programs, you should see the following hierarchy displayed for each server: WPS Server node: The root node that represents the WPS installation where you are running your programs, whether this is on a local or remote host. And then, under this node: Libraries: A parent node for individual library items. Library: A collection of catalogs and/or datasets. Refer to Libraries. 41

42 You may also see a library node called Work. This represents the default temporary library used if one is not specified in a program. If you use the LIBNAME statement in a program to specify your own library name, then you will see a library node with the specified name also listed in the view. Catalog: A collection of user-defined items such as formats and informats. Dataset: A data file containing numeric and/or character fields. Dataset View: A dataset that is created by invoking a view in the source data. For details about listing and opening datasets, refer to Working with the Dataset Viewer. Numeric Dataset Field: A dataset field that contains numeric values. Character Dataset Field: A dataset field that contains character values. Filerefs: The parent node for Fileref items. Fileref: An individual reference to a file. Although Filerefs are generated automatically, you can also create them yourself by using the FILENAME statement, for example: filename shops 'c:\users\fred\desktop\4.1-shops.xls'; will allow you to reference the above pathname without repeating it in full. For example, you could use the reference in a DATA statement to read data from c:\users\fred\desktop\4.1shops.xls, as in: DATA shops; INFILE shops DLM = ',' DSD MISSOVER; LENGTH ShopName $20.; INFORMAT Opened DDMMYY10.; INPUT ShopName Opened FirstYear SecondYear ThirdYear FourthYear FifthYear; The link between a Fileref and its associated external file lasts only for the duration of the current WPS session, or until you change it or discontinue it by using another FILENAME statement. If you wish to keep a Fileref from session to session, then save the FILENAME statement within the relevant program(s). To view the details for a particular Fileref, right-click on it in and select Properties. Properties If you select any item in the WPS Server Explorer view, other than the Libraries and nodes, you will see information about that item displayed in the Properties view. Filerefs You can also display more detailed properties about certain items by right-clicking on an item, and, from the context menu, selecting the Properties option if it is enabled (that is to say, if there are properties available for the selected item). The following are examples of what you might see: WPS Server Properties 42

43 Refer as appropriate to Local WPS server properties or Remote WPS server properties. Library Properties General: The access details (for example, Read-only or Temporary), together with the name, engine and location details. Members: A table of information about the members of the catalog, showing the member name and member type for each. Catalog Properties Entries: A table of information about the entries in the catalog, showing the entry name, entry type and description for each. General: Name of the catalog. Catalog Entry Properties General: Name, type, description, creation and modification time of the entry. Dataset and Dataset View Properties General: The field count and number of observations. Columns: A table of information about the dataset fields, including name, type, length, label, format and informat. Local WPS server properties The following properties and information are available for a local server: Some items are only available when the server is running, and, where this is the case, it is noted. Code Submission If, before any program is submitted to the server, you require the working directory on the server to be set to be the same as the directory from which the program is opened, select the option shown here (Set the server working directory to program directory on submission). This setting of the working directory should then happen automatically provided that the directories are on the same host. If the directories are not on the same host, then the working directory on the server is set to be the Initial current directory for server process specified in Startup (see below). If the option Set the server working directory to program directory on submission is not selected, then no changes are made to the working directory when a program is submitted to the server. Environment This section lists details of the server's environment (working directory, process ID and environment variables). This information cannot be modified, and is only available when the server is running. 43

44 Macro Variables This section lists the automatic and global macro variables used by the server, and the associated values. This information cannot be modified, and is only available when the server is running. However, you can click Add... to create new variables. System Options This lists the names of all the system options that are currently set on the server, along with their values. This is the same information as would by provided via the PROC OPTIONS statement. The information cannot be modified, and is only available when the server is running. WPS Licence Information This page shows the setinit information for the server, such as the products that are licensed, the amount of grace or warning time on the licence, and the date on which the licence expires. This information cannot be modified, is only available when the server is running. WPS Software Information This page shows details about the WPS software, including the version number and the operating system on which it is running. This information cannot be modified, and is only available when the server is running. Startup The main page has a flag called Start the server automatically on connection startup. Ensure that this is selected if you wish the server to be started automatically whenever the associated connection is launched. The Initial current directory for server process entry is where you specify the working directory for the server, determining where the output is generated. If you have %INCLUDE statements in your code with relative paths in them, then it is important that you start the server in the correct directory to allow those %INCLUDE statements to find the files they are including. The Startup page has two further sub-pages: System Options. When the server is running, this page allows you to specify any WPS options that you would like to pass to the server to process on startup, for example WPS server LOCALE and ENCODING settings, and other options that you can pass to WPS in Command Line mode. If you click Add... you will see a new popup dialog that allows you to click 'Select...' to choose an option that is to be set. After choosing the option, you can set the associated Value, before clicking OK to make the option and value active. You can then use the Edit... and Remove buttons to modify and delete any options and values that you have previously created. Environment Variables. This page allows you to specify any environment variables that you would like to be set before the server is started. By clicking New..., you can specify the name of the variable and the value to which it is to be set. The item will then appear in the list. You can then use the Edit... and Remove buttons to modify and delete any environment variables that you have previously created. 44

45 Remote WPS server properties The following properties and information are available for a remote server: Some items are only available when the server is running, and, where this is the case, it is noted. Code Submission If, before any program is submitted to the server, you require the working directory on the server to be set to be the same as the directory from which the program is opened, select the option shown here (Set the server working directory to program directory on submission). This setting of the working directory should then happen automatically provided that the directories are on the same host. If the directories are not on the same host, then the working directory on the server is set to be the Initial current directory for server process specified in Startup (see below). If the option Set the server working directory to program directory on submission is not selected, then no changes are made to the working directory when a program is submitted to the server. Environment This section lists details of the server's environment (working directory, process ID and environment variables). This information cannot be modified, and is only available when the server is running. Macro Variables This section lists the automatic and global macro variables used by the server, and the associated values. This information cannot be modified, and is only available when the server is running. However, you can click Add... to create new variables. System Options This lists the names of all the system options that are currently set on the server, along with their values. This is the same information as would by provided via the PROC OPTIONS statement. The information cannot be modified, and is only available when the server is running. WPS Licence Information This page shows the setinit information for the server, such as the products that are licensed, the amount of grace or warning time on the licence, and the date on which the licence expires. This information cannot be modified, is only available when the server is running. WPS Software Information This page shows details about the WPS software, including the version number and the operating system on which it is running. This information cannot be modified, and is only available when the server is running. WPS Software Install Location This page shows the location of the remote WPS installation specified during server setup (refer to Defining a new WPS server). 45

46 Startup The main page has a flag called Start the server automatically on connection startup. Ensure that this is selected if you wish the server is to be started automatically whenever the associated connection is launched. The Initial current directory for server process entry is where you specify the working directory for the server, determining where the output is generated. If you have %INCLUDE statements in your code with relative paths in them, then it is important that you start the server in the correct directory to allow those %INCLUDE statements to find the files they are including. The Startup page has one further sub-page: System Options. When the server is running, this page allows you to specify any WPS options that you would like to pass to the server to process on startup, for example WPS server LOCALE and ENCODING settings, and other options that you can pass to WPS in Command Line mode. If you click Add..., you will see a new popup dialog that allows you to click 'Select...' to choose an option that is to be set. After choosing the option, you can set the associated Value, before clicking OK to make the option and value active. You can then use the Edit... and Remove buttons to modify and delete any options and values that you have previously created. Properties You can display properties of various objects by using the Properties view. The properties that appear in this view dynamically change depending on the item that is currently selected. To display this view To add this view to the current perspective, select Window Show View Properties. Views that interact with the Properties view If you click on an object in one of the views listed below, you will see the appropriate properties for that object displayed in the Properties view: Project Explorer WPS Server Explorer Search File Explorer Link Explorer Not all objects in the views listed above have viewable properties - for example, you cannot view properties for a host connection in the Properties view. 46

47 Editor When you open any type of file in the Workbench, for example programs, logs, output, datasets, text files, and so on, it is opened as a tab in the Editor. This view is always available and cannot be closed, and for this reason it is not listed under Window Show View. However, you can close individual files that are open in the Editor. It is possible to split the Editor so that you can view and/or modify two or more files at once, by selecting Window Editor Toggle Split Editor (Horizontal) or Window Editor Toggle Split Editor (Vertical). You can also open another copy of the current file by selecting Window Editor Clone. To create a new program within the Editor, refer to Creating a new program. You should also refer to the Text-based editing features that can be used within the Editor. Whether or not you can edit a file once it has been opened depends on its type, for example: You cannot edit logs and output files opened from the Output Explorer. You can edit a dataset that has been opened from the WPS Server Explorer, once you have switched to Edit mode (refer to Editing a dataset). Files opened from the Project Explorer can normally be edited. You can even select which editor to use when opening the file (as discussed in Working with editors). You can also open files for editing from the File Explorer. Bookmarks You can add bookmarks on any line inside a program, or indeed inside any file that you can open and edit with the Workbench via the Project Explorer. To list and navigate between your bookmarks, you can use the Bookmarks view. Refer also to Bookmark anchors. This view lists all bookmarks regardless of whether or not the associated programs are open. It does not list bookmarks from programs in a closed project. It is not possible to create bookmarks on files opened from the File Explorer, unless they are members of a project. This is because files opened outside of Projects may be located anywhere in a file system on a local or remote host, and bookmarks can only be set on files that are members of a workspace project. To display this view To add this view to the current perspective, select Window Show View To display a bookmark listed in the view 47 Bookmarks.

48 Either double-click on the required task, or right-click on it, and, from the context menu, select Go To. The relevant file will then be opened (if it was closed), and the bookmarked line will be highlighted (or else the first line in the file if the entire file was bookmarked). Tasks You can add Task markers (reminders) against any line in a program that has been opened from the Project Explorer, and associate each of them with notes and a priority level. To list, update and navigate between any tasks you have added, you need to use the Tasks view. The Tasks view lists tasks regardless of whether or not the programs are open. It does not list those from programs in a closed project. It is not possible to create tasks on programs opened from the File Explorer, unless they are members of a project. This is because programs opened in this way may be located anywhere in a file system, and tasks can only be set on files that are members of a workspace project. To display this view To add this view to the current perspective, select Window Show View Other General Tasks. This view allows you to change the priority levels of tasks, modify the descriptions, and either them as completed or leave them uncompleted. mark To display a task listed in the view Either double-click on the required task, or right-click on it, and, from the context menu, select Go To. The relevant file will then be opened (if it was closed), and the line containing the task will be highlighted. Outline (of structural elements) To assist in navigating programs, logs, listing or HTML output, the Workbench displays structural elements from these items in the Outline view. If you click on a structural element in this view, the relevant line in the file will be highlighted. Opening or giving focus to a program, log, listing or HTML result file, automatically refreshes the Outline view to display the structural elements that are relevant to the active item. To display this view To add this view to the current perspective, select the menu item Window Show View 48 Outline.

49 Program structural elements Opening programs causes the Outline view to display the following structural elements: Global statement DATA step Procedure Macro You can control which structural elements are displayed in the program's Outline view. In the toolbar at the top of this view you will see buttons with diagonal lines through them representing structural elements: These buttons can be used to toggle off and on the relevant structural elements in the view. Log structural elements The Outline view displays the following structural elements in the log: An individual log entry, and the parent node for errors and warnings. Error Warning Listing and HTML Structural Elements Viewing the results of program execution (refer to Viewing the listing output and Viewing the HTML output) causes the Outline view to display the following structural elements: Results parent node HTML tabular output Listing tabular output Output Explorer The output files generated from running a program, are listed by, and can be opened from, the Output Explorer view. To view hierarchical lists of results, grouped by server, use the Results Explorer. While the Workbench is open, the output from previous runs is not automatically deleted. In order to clear previous output, you can use WPS Clear Log or WPS Clear Results, or the relevant toolbar buttons or context menus. 49

50 Alternatively you can restart the server (as described in Restarting the server). To display this view To add this view to the current perspective, select Window Show View Output Explorer. Output Output items are associated with, and listed below, the server on which they were generated. The following output items are shown under a server if that server has executed programs that have generated output of one or more of the following types: Listing output HTML output PDF output Log output is always shown under each server, regardless of whether any programs have been executed. Once you execute a program that generates output of one of the above types, you will see the related output nodes appear below the WPS server by which they were generated. There is only ever one node shown for each type of output under each registered WPS server. Double-clicking on one of the output nodes opens the associated output in the editor associated with that ouput type (or in Adobe Acrobat for PDF output). If the output type is anything other than log output, then, at the same time as the output is opened in the editor, the individual result elements are listed in the Results Explorer. For further information on the types of ouput, refer to Working with program output. Results Explorer This view contains hierarchical links to all the results from every program that has been executed, grouped by server, since the last time that the particular server was started or restarted To view all output, including the log, use the Output Explorer. To display this view To add this view to the current perspective, select Window Show View 50 Results Explorer.

51 Output Once a program has been executed, an entry appears under the relevant server for every PROC that produced output. For example PROC PRINT will produce an entry named The PRINT Procedure. Expand this link to find links to each type of output that has been generated. For further information on the types of output, and the defaults, refer to Managing ODS output. Progress When you are running programs, their execution is confirmed in the Progress view. In addition, operations performed in the File Explorer are also visible here (both operations that are in progress, and those that are complete). While a program is being executed, and during File Explorer and WPS Server Explorer operations, there is also a progress indicator displayed in the lower right hand corner of the Workbench. This indicator is displayed regardless of whether or not you have the Progress view open. If a program is submitted to run while another one is still executing, it is listed as waiting to execute. If you wish to halt the execution of a program, click execution). in the Progress view (refer to Stopping an To display this view To add this view to the current perspective, select Window Show View Progress. File Explorer operations A File Explorer operation remains in the Progress view until another operation is performed. This allows you to see the results of the operation, if desired, by clicking on the associated link. The resultant information box displays: Status: Success or Error Operation: Copy, Rename, Delete, and so on. Source: Original location of the file or folder Destination : The target folder or root. Exception: Any errors that occurred when the operation was performed. When part of an operation fails, the Workbench still attempts to complete any other parts of the operation. For example, if you attempt to delete 5 files, and the first one fails, it will still attempt to delete the remaining 4 files. 51

52 Console (for remote server standard output) The Console view is not used if you are only running programs on a local server. It can, however, be extremely useful if you are running your programs on a remote WPS server. In this scenario, all standard output and standard error output produced by the server are echoed on the Console view. An example of its use could be to run an X statement in your program on the remote server which might be requesting a listing of the contents of a particular directory. In this case, the output from running the X statement is displayed. It is also extremely valuable when a remote server fails to start, or terminates abnormally. In this situation, error text is also displayed in the Console view. If you are using WPS Link, then, as explained in the Link Explorer, program output from a remote server can be viewed and manipulated from inside WPS Workbench, just as if the work had been executed locally. To display this wiew To add this view to the current perspective, select Window Show View Other General Console. Search This view displays the results of searches that are carried out using the Search dialog. When you click on an item in the results, the file opens automatically in the Editor at the exact place in the file where the item appears. Proceed as follows: 1. To open the Search dialog and add the Search view to the current perspective, do one of the following: Select Search Search. Select Window Show View Other General dialog Search using the following fields: 52 Search and launch the Search

53 Containing text: You can use any of the wild cards that are listed in the dialog. File name patterns (separated by commas): After entering any of the listed wild card prefixes, you can click Choose... to select the prefixes of file types to be searched for. Scope: You can, for example, select Workspace to conduct a search of all open projects in the Workbench, or Selected resources to conduct a search of only the active file. Tip: You can also click Replace... to specify a string that is to replace the one in the Containing text field. 53

54 Working with views This section describes how to manipulate the Workbench views both individually and as part of overall view stacks. View stacks A view stack is a window formed by a collection of views that are all allocated the same area in a perspective. For example, the view stack below contains 2 views: An individual view is opened in the view stack of which it was last a member. For example, if the Progress view was previously a member of our example view stack, then re-opening it restores it to the stack: 54

55 View stacks are an important concept to understand when it comes to moving, minimizing, maximising and restoring views. Opening a view To open a view in the Workbench: 1. Select Window Show View. 2. If the required view is not immediately listed, then select Other... from the drop-down menu to see a complete list of views. You will be presented with a list of all the available views grouped under category folders. 3. Highlight the view that you wish to open. 4. Click OK to complete the task. The view you select will open (if it was not already open) and will automatically become active. Its opening position will be in the view stack of which it was last a member. Closing a view To close a view that is open in the Workbench: 1. Ensure that the view is active by clicking on its tab. 2. Click on the close icon in the tab of that view. If you close all the views in one of the View stacks, then the adjacent view stack will expand to take up the available space. An exception to the above is the Editor view, which always remains open, even after you close all the programs that are open within it. Moving a view To move a view to a new window in the Workbench: 1. Click on the view tab or title bar and, while you keep pressing on the left mouse button, drag the view over the Workbench window where you want your view to appear. 55

56 2. Without dropping the view, move it around from side to side and up and down. You will see the new window start to divide, according to the dimensions of the view. Vertical and horizontal lines indicate where the view will appear if you drop it in its current location.. 3. Drop the view where you would like it to appear. 4. The view appears in its new view stack. If you dropped it onto an existing view stack, then the views in the original stack reduce in size to accommodate the new view. You can also move a view to a window outside Workbench, so that it is detached. Refer to Detaching and re-attaching a view. Detaching and re-attaching a view You can detach any individual view from the Workbench to create a new, detached window. To detach a view: Click on the view tab or title bar and, while you keep pressing on the left hand mouse button, drag the view off the main user interface. When you drop the view, a new window is created on your desktop away from the Workbench. To re-attach the view: 1. Drag the tab of the detached window (not its title bar) over the main Workbench window. Rectangles will appear to incidate where the view can be dropped. 2. Drop the view in the desired position. The detached view should now revert to being docked in the Workbench. If you close a detached view, it will still be detached when you next open it. Resizing a view In order to resize a view, you have to resize its associated view stack, which will then resize all the views within it. 1. Move your mouse over the border between the particular view stack or window, and its adjacent view stack or window (whether this is to the side, above or below), until the cursor changes to the or resize icon. 2. Press your left mouse button and keep it pressed while you drag the border side to side, or up and down. 3. Release the mouse button to complete the resize operation. 56

57 Minimising a view In order to minimise a view, you have to minimise its associated view stack, which will then minimise all the views within it. The minimised views will then be represented by icons on either the left or right of the Workbench, so that you can restore them, for example: To minimise a view stack or window, click Minimise button on the view stack or window. Maximising a view In order to maximise a view, you have to maximise its associated view stack, which then fills the entire Workbench interface. To maximise a view stack or window, do either of the following: Maximise on the view stack or window. Click Double-click on either the view stack's toolbar or the tab of one of the views within the stack. Maximising a view causes it to occupy as much space as it possibly can. When this happens, other views that occupy the same view stack are also maximised, but the original view remains on top, and is still active. All other view stacks are minimised to the edges of the Workbench window, where they are represented as icons. Restoring a view In order to restore a view to its 'normal' state after it has been minimised or maximised, you have to restore its associated view stack. To restore a view stack or window that has been maximised, do either of the following: 57

58 Restore button of the view stack or window. Click on the Double-click on either the view stack's toolbar or on the tab of one of the views within the stack. To restore a view stack or window that has been minimised, do either of the following: Restore icon above the minimised view stack to restore all the views in that stack. Click the Right-click on the relevant icon on either the left or right of the Workbench to display the context menu, and then select Restore: Perspectives The positions of available views, windows, view stacks, menu items, and toolbar buttons, together with any other items that make up the general layout of WPS Workbench, together constitute a perspective. We have already covered the default WPS perspective. However, this can be customised to look the way you want by moving, resizing, adding or removing different views (refer to Working with views). The Workbench allows you to save customised perspectives and to switch between different perspectives. WPS remembers when you next open the Workbench, exactly how the windows and views, and so on, were arranged, when you last closed it. You do not even have to save a perspective to ensure that this happens. This ensures that your favourite perspective is immediately visible as soon as you open the Workbench. Opening a perspective To open a different perspective: 1. To see a list of all the available perspectives in the Open Perspective dialog, either select Window Open Perspective Other or click the Open Perspective icon in the top right of the screen: 58

59 2. Highlight the perspective that you wish to open. 3. Click OK to complete the task. When you open a perspective, its name is highlighted by default in the top right of the Workbench. If you have other perspectives available, they are also listed in this area, to the right of the Open Perspective icon, so that you can click on them to switch between them quickly. Closing a perspective The quickest way to close a perspective is to go to the area to the right of the Open Perspective icon, right-click on the perspective required, and then select Close. Alternatively: 1. If you have more than one perspective open, ensure that the Workbench is displaying the one that you wish to close. To switch perspective, look in the area to the right of the Open Perspective icon, and then click on the perspective required. 2. Select Window Close Perspective. If you wish to close all the perspectives, so that only the Default WPS perspective remains available for selection, select Window Close All Perspectives. Your interface will go blank. To restore the default perspective, select Window Open Perspective Other WPS (default). Resetting a perspective You can reset the current perspective back to its default layout at any time, by proceeding as follows: 1. Select Window Reset Perspective. 2. You are prompted for confirmation that you wish to reset the perspective. Click Yes to confirm that you wish to do so. 59

60 Saving a perspective If you have changed the layout of a perspective, you can save it under a user defined name for future use, as follows: 1. Select Window Save Perspective As. 2. Enter a name for the perspective at the top of the Save Perspective As... dialog. 3. Click OK to continue. If a perspective is already saved with the name you have just entered, you will be asked if you wish to overwrite it with the new perspective layout. The new perspective appears in the top right of the Workbench, to the right of the Open Perspective icon. A perspective derives its icon from the one that you had open when you saved it. Deleting a perspective To delete a perspective: 1. Select Window Preferences. 2. From the left hand tree view of the Preferences window, select General Perspectives. 3. From the list of Available perspectives, click on the perspective that you wish to delete. 4. Click Delete to remove the perspective permanently. There is no confirmation prompt. You can only delete user-defined perspectives. In other words, you cannot delete a perspective that was supplied with WPS, including the default WPS perspective. 5. Click OK to close the Preferences window. 60

61 Projects A project is a Workbench representation of a parent folder containing objects such as programs, files and folders. This parent or project folder is defined by a Project Definition File. WPS uses a project to hold the files and folders that relate to each other. For example, you might have one project containing programs that are still under development, another project for monthly reporting applications, and so on. Each project is in turn held in its own parent folder referred to as a workspace. You can only work with one workspace at a time within the Workbench, but you can switch between different ones as required (refer to Switching to a different workspace). The Project Explorer is used to display and manage the current workspace and the projects it contains. There is no limit to the number of projects you can have open within WPS Workbench, or to the number of folders and files that a project may contain. Files may also be of any type, and all the typical operations that you would expect to be able to perform on files are available, including the ability to execute files identified as SAS programs (that is to say, any files with the extension.sas or.wps). Workspace objects can be managed using Local history, and they can also be exported to archives or to other folders in a file system on a local or remote host, and such archives may also be imported in this view. If you would prefer to access a file system directly in order to manage programs (rather than use projects), then this is possible via the File Explorer (although using this will not give you access to Local history). Project Definition File There is a project definition file called.project in the root directory of a project. This file contains information about the project that is used internally by the Workbench. This file is not normally displayed by the Project Explorer. However, if you look at the project folder outside of WPS Workbench, you can see it. Caution: Do not delete or edit this file. Do not move this file from the root directory of the project folder, even into another project folder. Do not copy or import this file into another project folder. 61

62 Managing projects This section of the guide covers the creation and manipulation of projects, and the files within them. Creating a new project To create a new project: 1. Launch the New Project wizard by either clicking the drop-down next to the New the top left hand corner of the window and selecting Project. icon in Project, or by selecting File New You will see the first page of the New Project wizard. 2. Expand the General folder and highlight the Project node. 3. Click Next. 4. Enter the new Project name. Provided that the name of the new project is not the same as that of an existing folder, a new folder will be created. 5. (Optional) If you wish to change the default location of the new project, deselect Use default location and specify the new Directory, using Browse where required. Caution: If you choose a directory outside of the active workspace, then you need to be aware that, by adding it to the project, you are not moving the folder. It is merely referred to by the project. 6. You need not concern yourself with the Project References page of the New Project wizard as this is mainly for Eclipse use. Therefore, click Finish to create the new project. Creating a new folder in a project You can have any number of folders and sub-folders in a project. To create a new one: 1. Launch the New Folder wizard by frst ensuring that the parent item is open, and then doing one of the following: Right-click on the Project or select New Folder. Select File New Click the drop-down next to the New select Folder within which you wish to create the new folder, and Folder. icon in the top left hand corner of the window and Folder. 62

63 You will see the first page of the New Folder wizard. 2. The parent defaults to the current project or folder. 3. Near the bottom of the window, type in the new Folder name. 4. (Optional) Clicking Advanced allows access to folder configuration options. Use default location. This is the default option. The folder will be created as a file system folder, in the original location. Folder is not located in the file system (Virtual Folder). The folder will only exist in the workspace and no folder will be created in the associated file system. You can create links to other files and folders within this new folder, and also add other virtual folders. To do this, simply drag and drop your other project resources into the virtual folder. It is not possible to create physical files and folders within virtual folders. You can use this option to organise an alternative view of files and folders independent of their physical location. Link to alternate location (Linked Folder). When you link a folder to an alternate location, the folder represents the contents of this folder in the alternate location directly. Any changes that you make to the contents will also affect the folder in the associated file system. The Workbench will record any changes to files that you make with the Workbench, allowing the use of Local history with these files. Use Browse... in order to select the folder in your file system to which to link. 5. Click Finish to complete the task. Creating a new file in a project To create a new file under an existing as follows: Project, or under an existing Folder in a project, proceed 1. Launch the New File wizard by doing one of the following: Ensure that you have the Project Explorer open (Window Show View Project Explorer), right-click on the object under which you wish to create the new file, and then select New File. Select File New Click the drop-down next to the New window and select File. icon in the top left hand corner of the Workbench File. You will see the File dialog. 2. Ensure that the required parent folder is selected at the top of the dialog. 3. Near the bottom of the dialog, type in the new file name. If you specify a file extension that the system recognises (for example,.sas or.wps or for a program, or.doc for a Microsoft Word document) then the new file will be associated with the appropriate editor. If no file extension is specified, or if the extension is not one that the system recognises, then the default action is to associate the new object with WPS Workbench Text Editor. 63

64 4. (Optional) Select Advanced and, if required, Link to file in the file system. Then use Browse to select an existing file, from any project, to which to link the new file. This step creates a shortcut to the existing file, and the contents of the latter will immediately be written to the new file. Any changes that you make to these contents will now also affect the file in the file system. The new file has a small arrow in the right hand corner of its associated icon, for example, to indicate that it is linked. To examine the nature of the link at any time, and change it if needed, right-click on the project file with the icon, and select Properties followed by Resource. 5. Click Finish to complete the task. The new file appears in the Project Explorer, under the selected Project or Folder. To create a new program file specifically, within which you can create a new in WPS, refer to Creating a new program file in a project. Program for execution Creating a new program file in a project To create a new program file below an existing proceed as follows: 1. Ensure that you have the Explorer). Project, or below an existing Project Explorer open (Window Show View Folder in a project, Project 2. Launch the New Program wizard by doing one of the following: Right-click on the object below which you wish to create the new progam, and then select New Program. Select File New Click the drop-down next to the New window and select Program, or File New Program or Untitled Program. icon in the top left hand corner of the Workbench Untitled Program from there. You will see the WPS Program dialog. If you selected Untitled Program, then the new program automatically opens in the SAS Editor ready for you to start typing in code, and it has a default name of Untitled n.sas, where n is the next number in the sequence. You can now start typing in code in accordance with Creating a new program, and save the file to the required location. 3. Ensure that the required parent folder is selected at the top of the dialog. 4. Near the bottom of the dialog, type in the new file name. 64

65 The Workbench may suggest a default name such as Program1.sas, or, if there is already a program using this name, Program2.sas, and so on. However, you can change the extension to.wps if you prefer, as files with both suffixes are handled as SAS programs by WPS. 5. (Optional) Select Advanced and, if required, Link to file in the file system. Then use Browse to select an existing file, from any project, to which to link the new file. This step creates a shortcut to the existing file, and the contents of the latter will immediately be written to the new file. Any changes that you make to these contents will now also affect the file in the file system. The new file has a small arrow in the right hand corner of its associated icon, for example, to indicate that it is linked. To examine the nature of the link at any time, and change it if needed, right-click on the project file with the icon, and select Properties followed by Resource. 6. Click Finish to complete the task. The new program appears in the Project Explorer, under the selected Project or Folder, and automatically opens in the SAS Editor ready for you to start typing in code, in accordance with Creating a new program. Opening a project file When using the Project Explorer, you have control over exactly how the Workbench should open your files, by selecting specific editors. Refer to Working with editors. Moving a project file To move any folder, file, program, or any other object, between projects, or between folders within the same project, proceed as follows: 1. Ensure that you have the Explorer). Project Explorer open (Window Show View Project 2. Highlight the object that you wish to move. 3. Move it by doing one of the following: Drag it to the required project or folder, making sure to keep the left mouse button depressed until the system indicates that you can drop it. Select the option File Move..., to display the Move Resources dialog. You can then select the new destination project or folder within the dialog, Preview the move as required, and then click OK to complete the move. 65

66 If you are not happy with the completed move, you can revert it by selecting Edit Undo Move Resources. Tip: You can also drag and drop objects between Microsoft Windows Explorer and the Workbench Project Explorer. Copying a project file To copy any folder, file, program, or any other object, between projects, or between folders within the same project, proceed as follows: 1. Ensure that you have the Explorer). Project Explorer open (Window Show View Project 2. Highlight the object that you wish to copy. 3. Do one of the following: Hold down the the Ctrl key, and drag it to the required project or folder while keeping the Ctrl key depressed. A dialog will be displayed asking whether you want to copy the object or link it to another location. Copy (by either right-clicking on the object and selecting Copy, or selecting Edit Copy from the menu), and then paste (by either right-clicking on the destination project or folder and selecting Paste, or selecting Edit Paste from the menu). If you are not happy with the completed copy, you can revert it by selecting Edit Undo Copy Resources. If you try to paste the object into the same location from which you are copying, you will be prompted to enter a new name for the copy (the default name is Copy of <object name>). Tip: You can also copy objects between Microsoft Windows Explorer and the Workbench Project Explorer, by copying and pasting or dragging and dropping. In addition, you can copy and paste files between the Project Explorer and File Explorer, and vice-versa. Renaming a project or project file To rename an object, or even the project itself: 66

67 1. Ensure that you have the Explorer). Project Explorer open (Window Show View Project 2. Highlight the object or project that you wish to rename. 3. Display the Rename Resource dialog by either right-clicking on the object and selecting Rename... from the context menu, or selecting File Rename from the main menu. 4. Enter the New name in the Rename Resource dialog. 5. Either press Enter on your keyboard, or click OK, to complete the operation and close the dialog. Linking the active file to the Project Explorer If you have several files from different projects open in the Editor, you can configure the Project Explorer to expand a project's contents automatically so that each open file is linked to the Project Explorer. This means, for example, that the name of a program is displayed and highlighted within its folder each time that you switch the focus to that program in the Editor. Restriction: This linking feature does not work for programs opened with the File Explorer. 1. Ensure that you have the Explorer). Project Explorer view open (Window Show View 2. On the view's toolbar, click the Project Link with Editor button. This toggles the linking feature on or off. Deleting a file from a project The removal of an entire project is covered in Deleting a project. To delete an individual object from a project, proceed as follows: 1. Ensure that you have the Explorer). Project Explorer open ( Window Show View Project 2. Highlight the object that you wish to delete. 3. Display the Delete Resources dialog by either right-clicking on the object and selecting from the context menu, or selecting Edit Delete from the main menu. Delete 4. Press OK to confirm you wish to proceed with the deletion. 5. The dialog is closed and the object is removed from its parent project. If you have multiple copies of the same object within various folders and projects, only the actual copy that is highlighted is removed. 67

68 If you delete objects as above, from within the Project Explorer, rather than using the operating system's deletion tools, you can use the Workbench's Restoring from local history feature. Copying a project You can use the Workbench's existing project. Copy and Paste facility to create a new project based on an For general information about this facility, refer to the Copying a project file section in this guide. Deleting a project To delete a project: 1. Ensure that you have the Explorer). 2. Right-click on the Project Explorer open ( Window Show View project and, from the context menu, select Project Delete. 3. A message is displayed allowing you to confirm or cancel the deletion. Warning: You will also see a check box option Delete project contents on disk (cannot be undone). Selecting this option will permanently remove the project folder and all its contents from the file system. You also have the option of being able to Preview the information associated with the resource that you are about to delete. This will highlight any potential problems. If you opt not to remove the contents from the file system, you can subsequently select File Import General Existing Project into Workspace, to redisplay the project in the Workbench. 4. Click OK to proceed with the deletion. Closing and re-opening a project When you have multiple open projects in the Workbench, you might like to to ensure that you do not accidentally manipulate the wrong programs: 1. Ensure that you have the Explorer). 2. Highlight the close some projects Project Explorer open ( Window Show View project that you wish to close. 68 Project

69 3. Either right-click on the project and select Close Project, or select Project Close Project from the menu. As well as collapsing the tree under the closed project in the Project Explorer view, any programs or other files that were open in the Workbench's Editor view are automatically closed. When you need to re-open the project: 1. Open the 2. Highlight the Project Explorer ( Window Show View Project Explorer). closed project. 3. Either right-click on the project and select Open Project, or select Project Open Project. Importing files To import files from either an archive file (such as a zip file) or from the file system: 1. You need to import files into an existing project. If you do not have an existing project, refer to Creating a new project. 2. Launch the Import wizard by either right-clicking on the project and selecting Import..., or selecting File Import from the main menu. You will see the first page of the Import wizard. 3. Expand the tree under the General node. 4. Select one of the following options: File System - Use this if the files and folders to import are not archived in a single file. Archive File - Use this if the files and folders to import are archived in one file (as a zip, tar or tar.gz, for example). 5. Click Next >. 6. In the blank From field at the top of the screen, you need to specify the location of the file(s) to import, using Browse as required. 7. You will see a list of the files and folders that are available to import. Ensure that all the objects that you wish to import are selcted. Tip: You are advised not to select the parent folder of the files to import - otherwise, in your new project, you will end up with your imported files inside a sub-folder that relates to this parent folder. Restriction: Do not import a Project Definition File (.project ). Otherwise, it will overwrite the one in the project that you are about to select in the next step as the Into Folder'. 69

70 8. Use Browse to specify the Into folder (that is to say, the folder into which the file(s) selected in the From field will be imported). 9. Click Finish. The files have been imported into the selected project. Exporting a project To make a copy or backup of a project and all the files and folders contained within it: 1. Ensure that you have the Explorer). 2. Highlight the Project Explorer open ( Window Show View Project project that you wish to export. 3. Launch the Export wizard by either right-clicking on the project and selecting Export..., or selecting File Export from the main menu. You will see the first page of the Export wizard. 4. Expand the tree under the General node. 5. Select one of the following Export Destination types: File System - Makes a copy of your project folder and the files and sub- folders it contains. Archive File - Creates a single compressed zip file in the export location. The Workbench can read and write zip files without the need for any additional proprietary software. 6. Click Next. 7. (Optional) You can now select or de-select any files and folders from the default list to be exported. Because you highlighted a project before you began the export process, the default list is made up from this project. If you want to change your selection, you could click Deselect All to ensure that nothing is selected, and then, in the left hand window, select the project that you want to export instead (this will ensure that all the objects it contains are selected). Experiment with the other options to select specific files and folders. 8. In the blank To field in the middle of the Export screen, you need to specify the target location. You can use Browse as required. 9. Click Finish to start the export process. You now have a backup of the project. Depending on which Export Destination you selected, if you look at the target location you selected, you will see either a zip file, or all the copied files and folders. 70

71 Working with multiple projects More than one project can be open at any one time in the Workbench. There are several ways to end up with multiple projects in the Workbench: Creating a new project Importing the sample and other projects Copying a project You can move, copy/cut and paste, items between projects. Switching to a different workspace To switch to a different workspace, so that you can display or create a different group of projects: 1. In order that you can see the outcome of switching workspaces, first ensure that you have the Project Explorer open ( Window Show View Project Explorer). 2. Select File Switch Workspace. If the workspace to which you wish to switch is not immediately displayed, select Other to display the Workspace Launcher (refer to the instructions there to select a different workspace). 3. If you selected an alternative workspace without displaying the Workspace Launcher, then the Workbench is automatically restarted to display the new workspace. Otherwise, launch the restart by clicking OK on the Workspace Launcher. Local history The Workbench maintains a local history of modifications to programs or other project files changed in the Workbench via the Project Explorer. Even when you close the Workbench and re-open it, the local history is preserved. Copying a program also copies its history, but only if you use the copy tools provided by the Project Explorer (refer to Copying a project file). Caution: Local history is not available when managing files through the 71 File Explorer.

72 History of Edits Each time you save a project file in the Workbench, a snapshot of the current contents of the file is added to the Workbench's local history. This history provides the ability to take any of your current programs and compare or replace them with local history (refer to Comparing with local history and Replacing with local history, respectively). Each modification in the local history is uniquely represented by the timestamp for each occasion the file is saved. If you modify a file outside of the Workbench, or modify a file opened with the File Explorer, no record will be added to the history. History of Deletions Each time you delete a program or file via the Project Explorer (refer to Deleting a file from a project), the edit history of the item being deleted is 'transferred' to the local history of the containing project or folder. This not only allows you to restore it from local history, but also to select which particular state from the item's history to restore. Local History Preferences Local history preferences allow you to control how long to keep the local history, how many entries to keep in the history, and the maximum file size that can be recorded. Comparing with local history To compare a current saved project file with a previous version: 1. Select the file for which you wish to compare versions in either of the following ways: Ensure that you have the Project Explorer open (Window Show View Explorer) and highlight the file. Open the file in the Editor and ensure that it is the active file. Project 2. Right-click and, from the context menu, select Compare With Local History. A History window opens showing the list of program revisions with revision times. 3. From the list of revisions, double-click a particular current version of the file. revision with which you wish to compare the The Text Compare window immediately opens showing the differences (marked in grey) between the two versions. The current version is shown on the left, with the revised version on the right. 4. The following toolbar buttons in the Text Compare window provide shortcuts to options that allow you to navigate through the files: Select Next Difference - when available, this option highlights the next difference. 72

73 Select Previous Difference - when available, this option highlights the previous difference. Select Next Change - when available, this option highlights the next modification. Select Previous Change - when available, this option highlights the previous modification. 5. If you wish to replace the entire current version with a previous version, then proceed as in Replacing with local history. If you simply wish to make more selective changes in the left hand window, based on what you see in the Text Compare window, the following toolbar buttons in the Text Compare window provide shortcuts to options that allow you to merge changes from one file to the other: Copy Current Change from Right to Left - this option copies the change/difference that is currently highlighted, from the right pane to the left pane. Copy All from Right to Left - this option copies the entire contents of the right pane to the left pane. 6. Once you have made your changes, select File Save. 7. Close the Text Compare window by doing one of the following: Close (this appears to the right of the name). Move the mouse over the tab and then select Right-click on the tab and select the Close option. Select File Close. If you try and close a window when there are unsaved changes, you will be asked whether or not you wish to save them. Replacing with local history To revert a program in a project back to a previous saved version: 1. Do one of the following: Ensure that you have the Project Explorer open (Window Show View Explorer) and highlight the file that you wish to replace with a previous version. Open the file in the Editor and ensure that it is the active file. Project 2. If you simply wish to replace the current version with the previous version, right-click, and, from the context menu, select Replace With Previous from Local History. However, if you wish to explore the previous versions before making a choice, proceed from the next step. 3. Right-click, and, from the context menu, select Replace With Local History. A Compare dialog opens showing the list of program revisions. 4. Double-click on a particular revision that you wish to compare against the current version. 73

74 The current version and selected previous version are displayed with the differences highlighted. The current version is entitled Workspace File, and the revision you selected is entitled Local History. Tip: You can highlight and copy a portion of text from a previous version that you wish to use elsewhere. Then, after clicking Close in the upper right hand corner of the dialog, or Cancel in the bottom right hand corner, you can paste your piece of text into a different program or file. 5. Once you are sure that the Local History version displayed is the one that you wish to use instead of the current version, click Replace to supersede the Workspace File with the Local History and close the Compare dialog. Restoring from local history A program or any other project file that has been deleted via the restored as follows: 1. Ensure that you have the Explorer). Project Explorer, can be Project Explorer open (Window Show View Project 2. To see all the files that have been removed from a project, right-click on the project. To see just the files that have been removed from a folder, right-click on the folder. Then, from the particular context menu, select Restore from Local History.... The Restore from Local History dialog opens showing the files that are available to be restored. 3. Select the check box next to each file to be restored. If a selected file has a local history, then the previous revisions of the file are displayed on the right hand side of the dialog, grouped by date. Once you highlight a revision, its details are displayed in the bottom pane of the dialog. Ensure that you highlight the revision that is to be restored, before continuing. 4. Click Restore to put the selected file(s)/file revision(s) back into the original project/folder and close the Restore from Local History dialog. Local history preferences By default, the Workbench keeps seven days of local history for each individual project file, with a maximum of fifty versions for each file. There is also a default of 1 MB of storage allocated for each program's local history. The above settings can be changed as follows: 74

75 1. Select Window Preferences General Workspace Local History. The Local History dialog is displayed. 2. Set any of the following as required: Days to Keep Files - The number of days that you want to keep records for any one project file. For example, if you type 20, then a history of saved versions from the last twenty days will be kept. The default value is 7 days. Maximum Entries per File - The number of versions to keep for any one project file. If this number is exceeded, the oldest changes are discarded to make room for the new changes. The default is 50 versions per file. Maximum File Size (MB) - The maximum file size (in MB) for a project file's local history. If this size if exceeded, then no more local history is kept for the file. The default size is 1MB. The Days to Keep Files and Maximum Entries per File are only applied when the local history is compacted on server shutdown. Comparing and merging multiple files You can carry out either two- or three-way comparisons. Three-way comparisons show the differences between three different versions of a file, for example the differences between the resource in the Workbench, the version of the resource that is committed in a branch, and the common ancestor on which the two conflicting versions are based. This feature is most useful when merging resources and there has been a conflict during synchronization. Conflicts are shown in red, incoming changes in blue, and outgoing changes in grey. If a common ancestor cannot be determined, for example because a resource with the same name and path was created and committed by two different developers, the comparison becomes a two-way comparison. To do this: 1. Ensure that you have the Project Explorer open (Window Show View Explorer) and highlight the files that you wish to compare (up to three). Project 2. Right-click and, from the context menu, select Compare With Each Other. If you are doing a two-way comparison, a Text Compare window immediately opens showing the differences (marked in grey) between the two versions. If you are doing a three-way comparison, you are first prompted to select the common ancestor - that is say, the file against which comparisons will be made. In the Text Compare window, the two versions other than the common ancestor are shown in adjacent panes, although you also have the option to show this latter pane as well via the following option on the toolbar: 75

76 Show Ancestor Pane - in a three-way comparison, this option shows the common ancestor. Click again to hide it. If you wish to switch between comparisons, you can use the following option: Toggle between Two-Way and Three-Way Comparison - this switches between the two-way comparison (ignoring the common ancestor) and three-way comparison. 3. The following toolbar buttons in the Text Compare window provide shortcuts to options that allow you to navigate through the files: Select Next Difference - when available, this option highlights the next difference. Select Previous Difference - when available, this option highlights the previous difference. Select Next Change - when available, this option highlights the next modification. Select Previous Change - when available, this option highlights the previous modification. 4. The following toolbar buttons in the Text Compare window provide shortcuts to options that allow you to merge changes from one file to the other: Copy Current Change from Right to Left - this option copies the change/difference that is currently highlighted, from the right pane to the left pane. Copy All from Right to Left - this option copies the entire contents of the right pane to the left pane. Copy Current Change from Left to Right - this option copies the change/difference that is currently highlighted, from the left pane to the right pane. Copy All from Left to Right - this option copies the entire contents of the left pane to the right pane. 5. Once you have made your changes, select File Save. 6. Close the Text Compare window by doing one of the following: Close (this appears to the right of the name). Move the mouse over the tab and then select Right-click on the tab and select the Close option. Select File Close. If you try and close a window when there are unsaved changes, you will be asked whether or not you wish to save them. 76

77 Managing files within the File Explorer In this section of the guide we will look a little more closely at how you can manipulate the various objects in the available file systems using the File Explorer. As previously explained in The Project and File Explorer views, the benefit of using the File Explorer is that you can access files and folders on remote systems as well as local ones. Creating a new folder in a file system Folders can be created wherever you have appropriate operating system privileges for the particular local or remote host. 1. Ensure that you have the File Explorer view open (Window Show View File Explorer). 2. Launch the New Folder dialog by right-clicking on the Directory Shortcut or which you wish to create the new folder, and selecting New Folder below Folder. You will see the New Folder dialog. 3. Ensure that the required parent Directory Shortcut or Folder is selected. You will see that the container from where you opened the context menu is currently selected. However, you may choose to create the folder on an entirely different host. 4. Near the bottom of the window, type in the new Folder name. 5. Click Finish to complete the task. Creating a new file in a file system To create a new file in an existing file system, proceed as follows: 1. Ensure that you have the File Explorer open (Window Show View 2. Launch the New File dialog by right-clicking on the Directory Shortcut or which you wish to create the new file, and then selecting New The New File dialog is displayed. 77 File. File Explorer). Folder below

78 3. Ensure that the required parent Directory Shortcut or Folder is selected. 4. Near the bottom of the dialog, type in the new file name. If you specify a file extension that the system recognises (for example,.sas or.wps or for a program, or.doc for a Microsoft Word document) then the new file will be associated with the appropriate editor. 5. Click Finish to complete the task. The empty file is created in the specified location. To create a new program file specifically, within which you can create a new in WPS, refer to the next section. Program for execution Creating a new program file in a file system Directory Shortcut or To create a new program file under an existing file system Folder, proceed as follows: 1. Ensure that you have the File Explorer open (Window Show View File Explorer). 2. Launch the New Program wizard by doing one of the following: Right-click on the object below which you wish to create the new progam, and then select New Program. Select File New Click the drop-down next to the New window and select Program, or File New Program or Untitled Program. icon in the top left hand corner of the Workbench Untitled Program from there. You will see the WPS Program dialog. If you selected Untitled Program, then the new program automatically opens in the SAS Editor ready for you to start typing in code, and it has a default name of Untitled n.sas, where n is the next number in the sequence. You can now start typing in code in accordance with Creating a new program, and save the file to the required location. 3. Ensure that the required parent Directory Shortcut or Folder is selected. 4. Near the bottom of the dialog, type in the new file name. The Workbench may suggest a default name such as Program1.sas, or, if there is already a program using this name, Program2.sas, and so on. However, you can change the extension to.wps if you prefer, as files with both suffixes are handled as SAS programs by WPS. 78

79 5. Click Finish to complete the task. The new program appears in the File Explorer, under the selected Directory Shortcut or Folder, and it will automatically open in the SAS Editor ready for you to start typing in code, in accordance with Creating a new program. Opening a file in a file system Opening files with the File Explorer allows the Workbench to decide which is the most appropriate editor to open them with. 1. Ensure that you have the File Explorer open. 2. Find the file you want to open, and double-click it. The file is opened according to the extension, for example: Program files (those with.wps and.sas file extensions) are opened in the SAS Editor. Text files (.txt) are opened in the Text Editor. XML files (.xml) are opened in the Text Editor. HTML files (.html) are opened inside the Workbench where possible (this is platform-dependent). Other types of file can also be opened in the Workbench, but this depends on the operating system. On some operating systems, the Workbench will attempt to open the application associated with the file, even if it cannot be opened inside the Workbench itself. Moving a file within a file system You can move files to other folders in your local and remote connections, by for example: Moving files using Cut and Paste. Moving files using Drag and Drop. Moving files using Cut and Paste You can move File Explorer objects by using the options on the Edit or right-click menu, or by using the keyboard shortcuts for your operating system. 1. Ensure that you have the File Explorer view open (Window Show View 79 File Explorer).

80 2. Select the object that you want to move and select Cut, or else use the keyboard shortcut for Cut for your operating system (for example CTRL + X). 3. Select the target Shortcut Directory or Folder to which you want to move the object and select Paste, or else use the keyboard shortcut for Paste for your operating system (for example CTRL + V). The progress of the operations can be viewed in the Progress view. Tip: You can also select multiple objects if you wish to move more than one object at once. Moving files using Drag and Drop You can drag and drop files and folders to move them: 1. Ensure that you have the File Explorer open ( Window Show View File Explorer). 2. Click on the object that you wish to move. 3. Press your left mouse button, and drag it to the required Shortcut Directory or Folder while keeping the mouse button depressed. 4. Release the mouse button to drop the object onto the selected location. The progress of the operation can be viewed in the Progress view. Tip: You can also select multiple objects if you wish to move more than one object at once. Copying a file within a file system You can copy files to other folders in your local and remote connections, by for example: Copying files using Copy and Paste. Copying files using Drag and Drop. Copying files using Copy and Paste You can copy File Explorer objects by using the options on the Edit or right-click menu, or by using the keyboard shortcuts for your operating system. 80

81 1. Ensure that you have the File Explorer view open ( Window Show View File Explorer). 2. Select the object that you want to copy and select Copy, or else use the keyboard shortcut for Copy for your operating system (for example CTRL + C). 3. Select the target Shortcut Directory or Folder to which you want to move the object and select Paste, or else use the keyboard shortcut for Paste for your operating system (for example CTRL + V). The progress of the operations can be viewed in the Progress view. Tip: You can also select multiple objects if you wish to copy more than one object at once. In addition, you can copy and paste files between the Project Explorer and File Explorer, and vice-versa. Copying files using Drag and Drop You can drag and drop files and folders to copy them: 1. Ensure that you have the File Explorer open ( Window Show View File Explorer). 2. Click on the object that you wish to copy. 3. Press the left mouse button and Control key, and keep them pressed as you drag the object to the required Shortcut Directory or Folder (depression of the Control key causes a plus symbol (+) to appear next to the mouse pointer). 4. Release the mouse button and Control key to drop a copy of the object onto the selected location. The progress of the operation can be viewed in the Progress view. Tip: You can also select multiple objects if you wish to copy more than one object at once. Renaming an object within a file system To rename a file system object: 1. Ensure that you have the File Explorer open ( Window Show View File Explorer). 2. Right-click on the required object and select Rename from the context menu. 3. The Rename File dialog is displayed, allowing you to overwrite the existing object name with a new name. 4. Press Enter or clicking OK will complete the operation and close the dialog. 81

82 You may need to refresh the connection in the Link Explorer view to see the change. (To do this, select the connection, and then either right-click on it and select Refresh from the context menu, or press the F5 key.) Deleting an object from a file system To delete an object from a file system, proceed as follows: 1. Ensure that you have the File Explorer ( Window Show View 2. Right-click on the required object and select 3. From the menu select the option File Explorer). Delete from the context menu. Delete. 4. Click OK to confirm that you wish to proceed with the deletion. Warning: Once you confirm the deletion of the object from the file system using the File Explorer, the operation cannot be undone. If you are deleting a file using the than using the Project Explorer (refer to Deleting a file from a project), rather File Explorer, you will be able to restore the files if required (refer to Restoring from local history). WPS File Explorer Preferences (Hidden Files) Under Window Preferences WPS File Explorer you can select Show hidden files and folders to allow hidden files and folders to be displayed on a Windows platform, or else the files and folders that start with a '.' character on UNIX-based systems. 82

83 Preferences There are many user settings, controls and defaults that you can control via the Window Preferences panel. Most of the relevant Preferences are incorporated into the sections of this guide to which they directly relate. This particular section covers just the following general options: Preferences filter General Preferences Shortcut Key Preferences Backing up your Preferences Any preferences that are not described in this guide can be looked up in the Eclipse-specific Workbench User Guide. Preferences filter The Preferences window has a filter function which can help you find preference pages quickly. Once you have opened the Window Preferences panel, you can see the filter function near the top left. It is a text box with the words type filter text: 83

84 By way of an example, type the word log into this box one letter at a time and see how the window is filtered to display only those pages whose titles or sub-titles contain the text that has been entered as a filter. To stop filtering, click on the Clear button that has now appeared on the right of the text box, and all available Preferencespages will then be redisplayed in the tree view. General Preferences Under Window Preferences General are controls that not only affect programs, but also other types of files and other general aspects of WPS Workbench. Here are some of the salient top-level items that you may wish to consider: 84

85 Always Run in Background Some operations such as running programs, or refreshing a project containing many files, can take a long time to be executed. When the Always Run in Background option is enabled, it allows such tasks to run without displaying the Executing window. If this option is left in its default unchecked state, then the Executing window has a Run in Background button that will have the same effect when selected. Show Heap Status When this option is selected, then an indicator is displayed showing information about usage of the current Java heap, which is the segment of operating system memory used by the Workbench to manage its GUI. This indicator appears in the bottom of the window to the left of the server status, for example: To increase your Java heap storage, update the last two lines of the file <wps_install_root>\eclipse\workbench.ini to something like -vmargs -Xmx1024m and then restart the Workbench. The -Xmx argument is the one that decides the Java heap storage limit, and in this case 1024 megabytes is the value. Workbench save interval (in minutes) The field indicates how often the state of the Workbench, including perspective layouts, is automatically saved to disk (the default is 5 minutes). Set to 0 if you want to disable this autosaving. Open Mode This preference controls the way you open objects in the Workbench. Select from the following: Double click - Single-clicking on a resource will highlight it and double-clicking on it will open it in an editor. This is the default action. Single click (Select on hover) - Hovering the mouse cursor over the resource will highlight it and clicking on it once will open it in an editor. Single click (Open when using arrow keys) - Selecting a resource with the arrow keys will automatically open it in an editor. Depending on which view has focus, selecting and opening a resource may result in behaviour different from that outlined above. Change Font Select Window Preferences General Appearance Colors and Fonts scroll down the Basic entries until you find Aa Text Font. Highlight this and then click Edit to apply a different font. 85

86 Shortcut Key Preferences If you wish to change any key bindings, select Window Preferences General Keys, and, under the Default scheme, search for the WPS category. Then filter the Category and Binding to display the following screen: If you wish to change any of the bindings, proceed as in the following example, where we want to bind Ctrl + 5 to the Cancel Edits command: 1. Ensure that the Cancel Edits command is selected. 2. In the Binding text box, press Ctrl

87 3. The right-most column (User) indicates that this is a user binding by displaying a U. If there was a conflict with another key, this column would also display a C. The binding will have the default context In Windows. If you wanted to change this, you could change the When field to the appropriate context (for example, Editing Text). 4. To save your changes and leave the Preferences dialog open, click Apply. To save your changes and close the Preferences dialog, click OK. If you wish to delete a binding, highlight the command and then either click Unbind Command or simply give focus to the entry in the Binding field and remove it using the Backspace key. Backing up your Preferences You can save your current Preferences to a backup file, and then re-import them if you want to go back to that particular set of Preferences at any time. To save your preferences to a backup file, proceed as follows: 1. Select File Export General Preferences. 2. Click Next. 3. The Export Preferences dialog is displayed: 87

88 4. Ensure that WPS Preferences and/or Keys Preferences (refer to Shortcut Key Preferences) is ticked. 5. Using the Browse button next to the To preference file field, specify either the name of a new backup preference file (the file will automatically be created with an extension of.epf), or the name of an existing backup file with an extension of.epf. If you specify the name of an existing file, then, if you do not wish to be warned when you are about to overwrite it, select Overwrite existing files without warning. 6. Click Finish to complete the creation of the backup file. To re-import preferences from a backup file, proceed as follows: 1. Select File Import General 2. Click Next. 88 Preferences.

89 3. The Import Preferences dialog is displayed: 4. Ensure that WPS Preferences and/or Keys Preferences (refer to Shortcut Key Preferences) is ticked. 5. Using the Browse button next to the From preference file field, specify the name of the existing backup file to be imported (it will have an extension of.epf). 6. Click Finish. 89

90 Creating a new program You can create a new program under either the Project Explorer or File Explorer. Refer tocreating a new program file in a project or Creating a new program file in a file system, respectively. You can then create and edit the program in the Workbench using the SAS Editor and the Text-based editing features. To assist in navigation, the Workbench displays the structural elements of a program in the (of structural elements). Outline Tip: If you are new to programs written in the SAS language, it may be advisable to look first at the programs in the sample project if you have not already imported them (refer to Importing the sample and other projects). These will give you an idea of syntax and the use of datasets. Once you have your emply program file open in the SAS Editor, proceed as follows: 1. Enter the code. The folllowing example shows you how to create a simple dataset of employees: /* Create a dataset */ DATA employees; LENGTH Name $10 Age 3 Job $15; INPUT Name $ Age Job $; /* Here is the data */ CARDS; Beth 41 Sales-Manager Steve 32 Sales William 35 Accounts Anne 28 Marketing Dawn 26 Sales Andrew 36 Support ; 2. Save your program by either typing Ctrl + S or selecting File Save. 3. Make any edits as required, referring as required to the Text-based editing features. The Workbench displays the language elements in the program using colour coding to help you to see the structure of the code. Some of the default colours used are green for comments, blue for keywords, and a yellow background for data lines, for example: 90

91 The colour coding also helps you to see if you have made a typing error with language elements. For example, in the sample program, change the word DATA on the second line to DAT and you should see it is displayed in red. Ensure you undo this typing mistake (by either typing Ctrl + Z or selecting Edit Undo Typing on your keyboard) before continuing. Important: If your program is not displaying any colour coding, then this is likely to be because it does not have an extension of either.wps or.sas. Without such an extension, it will not be able to be executed. 4. Run the program in accordance with Running a program from inside the Workbench. Any datasets that are generated, as is the case with the above example, are created in the Work location under Libraries, and can be edited in accordance with Editing a dataset. 91

92 For the remainder of the program output, refer to Working with program output. WPS Syntax Colouring The Syntax Colouring dialog under Window Preferences WPS Syntax Colouring allows you to specify how to display the language items contained in a program (data lines, comments, formats, and so on): 92

93 For each different type of language item, you can specify attributes relating to Color, Background Color and whether the item should be displayed in Bold oritalic. Entering WPS code via templates You can select Window Preferences WPS Code Templates in order to define templates that can be entered as code shortcuts into programs. These templates can be accessed through the normal code completion key sequence (typically, CTRL + Space). For example if you define a code template with the name template1, you can type temp followed by CTRL + space and the code completion feature will execute the following actions: 1. Match temp against the list of code templates. 2. Find your template called template1. 3. Enter the Pattern associated with the template into your program. 93

94 If there is more than one code template whose name starts with temp, then you will be presented with a dialog to allow you to select the template to be used. The Pattern containing the code to be entered into your program can be as simple or as complex as you like. It could just be a single word. For example, you could define a code template to expand to the name of a frequently used dataset for which the name is difficult to type. A code template could also define a large amount of text, for example, a boilerplate invocation of a particular procedure. If you are entering a variable into a Pattern, then it needs to be enclosed within pairs of '$$' characters. You can export code templates to an external file, or import them from a previously exported file. This allows you to share code templates with colleagues, or to copy code templates that you have defined between workspaces. Dynamic Help for Language Elements The Workbench can build a search term to use for searching the WPS Reference for Language Elements guide while you are writing or editing a program: 1. Unless you already have the context-sensitive Help view open in the Workbench (refer to Online help), press F1 on your keyboard to open it. 2. As you type in a new word, or point to an existing word within a program, then, as soon as the Workbench thinks it recognises it, the Help view will automatically build a search term to use to search the WPS Reference For Language Elements guide. The search appears in the More results: section of the current help topic. 3. Click on the search term to perform the search. Relevant topics will be listed in the Help view to assist you with writing your program. 4. When you have finished reading the help, click on the Related Topics link (on the top right of the Help view) to return to the context-sensitive help page (otherwise, the view will not be updated automatically as you continue to use the Workbench). Using Program Content Assist The SAS Editor provides a content assistance feature that suggests language elements. When you select these elements, they are automatically entered into your program. Proceed as follows to select one: 1. Type a word into a program that may be associated with language elements. For example, type the word PROC. 2. After the word, type a single space character. 94

95 3. Now press CTRL + SPACEBAR. If there are any expected language elements after the word you typed in step 1, then a popup list is displayed of these elements. 4. (Optional) You can filter the list by typing in the first letter(s) of the language element that you think you may want to use. 5. Double click on the language element you want and it will appear in your program. WPS Code Injection You can select Window Preferences WPS Code Injection in order to enter code that is to be executed automatically immediately prior to the running of a program, and/or immediately following the running of a program. Enable custom pre-code injection When this option is enabled, the code in the associated text box is executed immediately prior to the running of a program. This option provides a facility similar to the INITSTMT option described in WPS Reference for Language Elements, except that, here, the code is automatically run before each program that is submitted (the INITSTMT system option is only processed on server startup). The setting Automatically Manage Result Types in the Result Options Preferences allows you to select the automatic creation of ODS destinations (so that you can, for example, easily view the results of your programs in HTML and PDF). However, the automatic creation of destinations may not be suitable for you, and, in this case, you can use the custom code injection facility to set up ODS destinations in a more suitable way. Enable custom post-code injection When this option is enabled, the code in the associated text box is executed immediately following the running of a program. This option provides a facility similar to the TERMSTMT system option described in WPS Reference for Language Elements, except that, here, the code is automatically run after each program that is submitted. The TERMSTMT system option is only processed on server shutdown. Code Analyser You can use the Workbench Code Analyser to scan the code of existing programs written in the SAS language. The Code Analyser is a feature of the Workbench and can therefore only be used on platforms on which Workbench is supported. The Code Analyser generates reports that indicate which of your existing programs will run unchanged in WPS, which programs may require modification to run, and which programs contain language elements not yet supported by WPS. 95

96 The Code Analyser allows you to: Analyse Program Compatibility whether your existing programs or projects contain any unsupported language elements. Analyse Language Usage lists language elements used in the selected programs or projects. The analysis indicates which elements are supported and which are not. Running analyses The Code Analyser can quickly analyse single programs, or all programs in multiple projects (using the Project Explorer) or folders (using the File Explorer). Programs that might normally be executed on multiple different platforms can be analysed together. Gather the programs from these other environments, copy them to your workstation and then run the analysis tools from Workbench. Analysing program compatibility You can analyse one or more programs to identify which contained language elements are supported in WPS. To analyse SAS language programs: 1. Select the files to be analysed: Select the required file or files to analyse in the Project Explorer or File Explorer. You can highlight programs in different projects or folders within the particular view. Select one or more projects in the Project Explorer to analyse all contained programs. Select one or more folders in the File Explorer to analyse all contained programs. 2. In the view corresponding to your selection, right-click on the selected items and from the short cut menu click Analyse, and then click Program Compatibility. When the analysis has finished, a Program Compatibility Report automatically opens in the Workbench. 96

97 This report contains details about unsupported language elements used in programs. It does not report on any supported language elements that were used in the programs. Analysing language usage You can analyse one or more programs to identify supported language elements used in one or more programs. To analyse SAS language programs: 1. Select the files to be analysed: Select the required file or files to analyse in the Project Explorer or File Explorer. You can highlight programs in different projects or folders within the particular view. Select one or more projects in the Project Explorer to analyse all contained programs. Select one or more folders in the File Explorer to analyse all contained programs. 2. In the view corresponding to your selection, right-click on the selected items and from the short cut menu click Analyse, and then click Language Usage. When the analysis has finished, a Language Usage Report automatically opens in the Workbench. 97

98 This report details the SAS language elements used in the selected programs, and you can explore the detail of this report in the Workbench, or export the content to Microsoft Excel Analysing mainframe programs The Code Analyser is a feature of the Workbench and can therefore only be used on platforms on which Workbench is supported. To analyse programs designed to run on a mainframe, copy the required programs from the mainframe to a workstation running the Workbench. When these programs are analysed, the Code Analyser will identify SAS language elements specific to the z/os platform. Before analysing programs copied from a mainframe to a workstation: We recommended you remove sequence numbers from your jobs. Ensure each program file has a file extension of.sas Package up the jobs on the mainframe using XMIT. Once transferred to the workstation, use XMIT Manager to un-xmit the jobs for analysis. XMIT Manager can only handle PDSs (Partitioned Datasets) and not PDSEs (Extended Partitioned Datasets). When downloading the XMIT files from mainframe to your workstation, you must specify FB (Fixed Block) with an LRECL (Logical Record Length) of 80 and with no ASCII/EBCIDIC conversion, truncation or CRLF translation. 98

99 Viewing or exporting an analysis report You can view the detail of a Code Analyser report in Workbench, or export the report detail to Microsoft Excel. When viewing a report in Workbench, you can navigate to more detail, and ultimately to the source program where an issue is located. The program compatibility report summary links to a list of programs analysed. From this list you can access a list of problem elements, see where those elements are used within a program, and navigate to the element location within the file. The language usage report summary displays the SAS language elements used in the analysed programs. From this list you can find the frequency of SAS language element usage, which programs contain the elements, and navigate to the element location within the file. Exporting analysis results to Microsoft Excel The results of a program compatibility report or language usage report can be exported to a Microsoft Excel spreadsheet for either further analysis or to preserve the report information. To export a report: 1. In the report summary page, click Export results to Excel. 2. In the Save as window, enter the required name for the spreadsheet, and browse to the required location before saving it. Analysis restrictions Because of the nature of the SAS language, the result of the analysis cannot be guaranteed, and reports should be treated as a guide for further analysis. The Code Analyser has some limitations: The Code Analyser will not report incorrect syntax. SAS language elements that are not currently supported in WPS are now shown in the Compatibility Report as unknown. The analysis reports do not currently contain information about the use of macro language elements and library engine (data access) elements. Their use is however supported in WPS. 99

100 Working with editors In any of the Perspectives supplied with the Workbench or that you have created, the Editor window is always displayed so that you can continue to write and modify files. In this section of the guide we will look at the various ways of opening files into this window with the different editors. Only one file can be active at any one time. This is the file that currently has focus within the Editor. You can open programs using either the Project Explorer or File Explorer. The Project Explorer offers more control than the File Explorer, which determines the most suitable editor automatically, based on the filename extension of the file being opened. Editing files within Projects allows you to use Local history to help you manage changes, and also provides the navigation and editing tools described under Text-based editing features. SAS Editor The SAS Editor provides features suitable for editing SAS programs, such as WPS syntax colouring. Only files with an extension.wps or.sas can be opened in this editor. Programs can be opened either via a project or directly from one of the available file systems. Programs opened from a project allow additional Workbench features to be accessed by local history. To open a program in the SAS Editor: 1. If your program belongs to a project, ensure that you have the (Window Show View Project Explorer). Project Explorer open 2. Navigate to the program you wish to open. 3. Either double-click on the program that you wish to open, or right-click on it, and, from the context menu, select Open With SAS Editor. If your program does not belong to a project, you can always drag the file onto the Workbench from the operating system's file system explorer, or any other appropriate external tool. You can also use the File Open File... menu option. The program is opened in the SAS Editor. The program assistance features described in Text-based editing features are available. 100

101 Text Editor The Workbench has a basic Text Editor. You can open a program with this editor but the contents will be treated as regular text - that is to say, no features are available for colour coding and so on. To open a file in the Text Editor: 1. Ensure that you have the Explorer). Project Explorer open ( Window Show View Project 2. Navigate to the file you wish to open. 3. If the file is a text file, then simply double-click on it. Otherwise, right-click on the file, and, from the context menu, select Open With Text Editor. The file is opened in the Text Editor. Most of the program assistance features described in Text-based editing features are available. System Editor If a file has an extension associated with an application installed on your computer (for example,.doc may be associated with Microsoft Word), then the System Editor will launch that application with the file in a new window outside the Workbench. To open a file with the System Editor: 1. Ensure that you have the Explorer). Project Explorer open ( Window Show View Project 2. Navigate to the file you wish to open. 3. Provided that the file is associated with a particular application, then right-click on the file, and, from the context menu, select Open With System Editor. If you wish to open the file with an application other than the one with which it is routinely associated, then select Open With Other... and then select an internal editor or an external program from the resultant dialog. The file is opened in a new window outside the Workbench, within the particular application. 101

102 In-Place Editor The Workbench supports OLE (Object Linking and Embedding) document editing. For example, if you have a Microsoft Word document in your project and use the In-Place Editor, the Word document will open in the Workbench's Editor, with Microsoft Word's pull-down menu options being integrated into the menu bar of the view. To open a file with the In-Place Editor: 1. Ensure that you have the Explorer). Project Explorer open ( Window Show View Project 2. Navigate to the file you wish to open. 3. Right-click on the required file, and, from the context menu, select Open With Editor. In-Place Provided that there is an OLE editor associated with the selected file, the program is opened in the In-Place Editor within the Editor. The menus and options associated with the linked application are available. Default Editor When you simply double-click on a file, rather than making a selection from the context menu, the Workbench opens the file using the editor last used to open that type of file, or, in the case of a new file type, the application associated with it. If you wish to open a file with an application other than the one with which it is routinely associated, then select Open With Other... and then select an internal editor or an external program from the resultant dialog. To open a file with the Default Editor: 1. Ensure that you have the Explorer). Project Explorer open ( Window Show View Project 2. Ensure you can see the file you wish to open. 3. Either double-click on the file, or right-click on the file and, from the context menu, select Open With Default Editor. The file is opened using the editor last used, or, failing that, in a new window outside the Workbench, within its associated application. 102

103 Text Editor Preferences Under Window Preferences General Editors Text Editors you can determine how programs are displayed in the SAS Editor, and how files are displayed in the Text Editor. For example, if you wish to set the background colour, go to the Appearance colour options panel in the Text Editors dialog, highlight Background colour, untick System Default, and then select the required colour via the Colour box. These Preferences only apply to files opened within the Project Explorer. Some of the Preferences that can be configured are: Undo history size (that is to say, the size of the 'undo' buffer in terms of the number of operations able to be undone) Displayed tab width Show line numbers Colours (current line, foreground, background, and so on) Details about the colours used to display language elements in the SAS Editor are controlled via the WPS Syntax Colouring preferences. Closing files Any file that is opened in the Editor has a tab labelled with the file name. To stop displaying the file in the Editor, do one of the following: Close (this appears to the right of the name). Move the mouse over the tab and then select Right-click on the tab and select the Close option. Select File Close. If you wish to close all open files at once, select File Close All. 103

104 Text-based editing features You can use the features described below within the SAS Editor to help you write and modify programs and other project files within the Editor. The same features are available within the Text Editor, with the exception of the Colour Coding of Language Elements. The features described are not available when managing files through the File Explorer. Left hand borders The left hand borders are used to display different features: In the outer left grey border, you will see annotations. In the inner left white border, you will see the expand and collapse controls for blocks of related language items. The white border is also used to display quick difference indicators. Annotations These can consist of the following displayed in the outer left grey border of a file: Bookmark anchors Task markers Search results Quick difference indicators A quick difference indicator in the inner left white border of a program shows that something has changed in that line of code since it was last saved: Indicates that a change has been made to the line of code. If you hover the mouse over this coloured block, a popup window will show you the code as it was prior to the change. Indicates that there is a new, additional line of code. Indicates the position where one or more lines of code have been deleted. When you save a program, the quick difference indicators will be cleared from the margin. 104

105 Navigating between annotations and quick difference indicators You can navigate between annotations within an individual program by using the main menu options Navigate Next and Navigate Previous (or pressing the keyboard options CTRL +. and CTRL +, respectively). As well as using these menu and keyboard options, you can also select Previous Annotation on the Workbench's main button bar. Next Annotation and Although Next Annotation and Previous Annotation would appear to imply that they are for annotations only, you can actually use them to navigate between annotations and quick difference indicators in any individual program that is open in the Editor view. To the right of each of the Next and Previous annotation buttons in the main button bar are drop-down menus. You can use these menus to select the markers and indicators between which you wish to navigate. Layout preferences The display controls for a program, including the current line, foreground and background colours, and whether to display line numbers, are user defined. Refer to the Text Editor Preferences section for more details. Colour Coding of Language Elements The colours used to display language elements in a related to WPS Syntax Colouring. program can be controlled via the Preferences Bookmark anchors A bookmark is an anchor that you can specify so that you can quickly navigate back to that point at any time in the future. It is not possible to create bookmarks on files opened from File Explorer, unless they are members of a project. This is because files opened outside of Projects may be anywhere in a file system on a local or remote host, and bookmarks can only be set on files that are members of a workspace project. There is no limit to the number of bookmarks that you can create. Using the Edit Add Bookmark menu option, you can either add a bookmark on a particular line within a program, or against an individual program file listed in Project Explorer. To bookmark lines within a file, you can also select Add Bookmark... from the context menu. You can list, and navigate between, all your bookmarks via the Bookmarks view ( Window Show View Bookmarks). 105

106 To navigate between your bookmarks, refer to Jumping to a particular project location. If you export a project, the individual bookmarks are not exported with it. Adding a bookmark To add a new bookmark on a particular line within a project file: 1. Open the program or file in the Editor. 2. Move your cursor into the far left grey border immediately to the left of the required line: 3. Either select Edit Add Bookmark from the menu, or right-click, and from the context menu, select Add Bookmark. 4. The Add Bookmark dialog is displayed, and you are prompted to enter a name for future reference. The name defaults to the contents of the selected line. 5. Either press Enter on your keyboard, or click OK, to complete the operation and close the dialog. You will now see a bookmark tag in the border, and a corresponding entry in the Bookmarks view (if it is open). You can use this view while Jumping to a particular project location. You can add a bookmark to a whole file, by highlighting it within the selecting Edit Add Bookmark from the menu. 106 Project Explorer, and then

107 Deleting a bookmark To delete a bookmark: 1. Open the Bookmarks view ( Window Show View Bookmarks). 2. Right-click on the bookmark's description, and, from the context menu, select Delete. 3. You are prompted to select Yes to confirm the deletion. Task markers A task marker represents a reminder about a work item. Against any line within a program you can add a task and associate a short description and a priority level of (High, Normal or Low). There is no limit to the number of task markers that you can add inside a program. It is not possible to create tasks on programs opened from the File Explorer, unless they are members of a project. This is because programs opened in this way may be anywhere in a file system on a local or remote host, and tasks can only be set on files that are members of a workspace project. You can then list and navigate between all your tasks via the Tasks view ( Window Show View Tasks ). To navigate between your tasks, refer to Jumping to a particular project location. If you export a project, the individual tasks are not exported with it. Adding a task To add a new task marker on a particular line within a program: 1. Open the program or file in the Editor. 2. Move your cursor into the far left grey border immediately to the left of the required line: 107

108 3. Right-click, and from the context menu, select Add Task. 4. The Properties dialog is displayed, and you are prompted to enter a descritption for future reference. The description defaults to the contents of the selected line. 5. Select the priority level (High, Normal or Low). 6. Click OK, to complete the operation and close the dialog. You will now see a open). task marker in the border, and a corresponding entry in the Tasks view (if it is Deleting a task To delete a task: 1. Open the Tasks view ( Window General Tasks). 2. Right-click on the task's description, and, from the context menu, select Delete. 3. You are prompted to select Yes to confirm the deletion. Jumping to a particular project location You can jump to a particular location in a project file: To jump to a bookmarked location: 108

109 1. Open the Bookmarks view ( Window Show View Bookmarks). 2. Either double-click on the required bookmark description, or right-click on it, and, from the context menu, select Go To. 3. The relevant file will then be opened (if it was closed), and the bookmarked line will be highlighted (or else the first line in the file if the entire file was bookmarked). To jump to a task: 1. Open the Tasks view (Window Show View Tasks). 2. Either double-click on the required task description, or right-click on it, and, from the context menu, select Go To. 3. The relevant file will then be opened (if it was closed), and the line containing the task will be highlighted. To jump to a particular line number: 1. Select Navigate Go to Line Enter the required number in the Go to Line dialog. 3. Either press Enter on your keyboard, or click OK, to complete the operation and close the dialog. To jump to the last edit: 1. Select Last Edit Location from either the toolbar or Navigate menu. The relevant file will be opened (if it was closed), the last line you edited will be highlighted, and the cursor will be placed at the end of the last piece of text you edited. Navigation between multiple project files You can have as many projects open in the Workbench as you like and each of these projects can contain any number of programs. You can open any number of programs and other files from the different projects in the Editor. For each program that is open, a corresponding tab is displayed. An open program can be given focus in the Editorwindow by clicking on its tab. Moving backwards and forwards between programs The main menu options Navigate Back and Navigate Forward (or and on the toolbar) are analogous to the back and forward buttons on a web browser. However, unlike a web browser, when you close and re-open WPS Workbench, it still has the navigational information. Back navigates to the previous resource that was viewed in the Editorwindow. Forward displays the program that was active prior to selection of the previous Back command. 109

110 Searching and replacing You can find any text string in an open program, as follows: 1. Ensure that the program to be searched is open in the File Explorer ( Window Show View File Explorer). 2. Display the Find/Replace dialog by either selecting Edit Find/Replace... from the menu, or pressing CTRL + F on your keyboard. The Find/Replace dialog is displayed, which allows you to specify the term to be found, and, if required, the term with which it is to be replaced. The default Scope is All, which means that the whole file is searched (you can amend this to Selected lines if required). The other options are those that you would expect to find in any search dialog and are self-explanatory. 3. Click Find to find the first instance of the word and then proceed as required, clicking Find to move to each new instance of the text string. If you select Close to remove the dialog, then the string is remembered, and selecting Edit Find Next and Edit Find Previous will conduct the same search, forwards and then backwards, without re-opening the dialog. Undoing and redoing your edits There is a multiple undo facility for project file edits, as follows: 1. Either select Edit Undo from the menu, or press CTRL + Z on your keyboard. The last change you made is undone. 2. Repeat the above step for each previous edit that you wish to undo. The number of undos that can be performed is determined by Undo history size in the Text Editor Preferences. You can also redo any undone edits on an incremental basis, by either selecting Edit from the menu, or pressing CTRL + Y on your keyboard, the requisite number of times. 110 Redo

111 Libraries A library is used to store WPS data files (including datasets), as well as folder locations and database connections via the LIBNAME statement. On the majority of operating systems, a library maps directly to an operating system folder. The operating system folder may contain non-wps files, but only the files with extensions that WPS recognises will be visible in the Workbench. The default Libraries that are set up under each server in WPS Server Explorer are as follows: SASHELP, a read-only library containing a variety of system metadata. SASUSER, which allows you to store datasets and other information that you want to keep beyond the end of your WPS session. Simply add sasuser. in front of the name of the relevant dataset in your program. Work, which is where your datasets, catalogs and Filerefs are stored by default. Work is a 'temporary working space' that is automatically cleared of all data when your WPS session ends. It is generally defined by the Work definition in the wps.cfg file in the root of your WPS installation, and is typically set to be -WORK '!TEMP\WPS Temporary Data', where TEMP is a Windows environmental variable that is typically defined to be a path on the C: drive. Instead of changing the wps.cfg file, you could either set Work to be a non-temporary location, as described in Set WORK location, or use the LIBNAME statement to write any data that you wish to keep, to your own permanent location (that is to say, directory or database connection). The LIBNAME statement assigns an alias to the specific location, and this is then used in subsequent programs in place of the name of the directory or database connection. The maximum length of a LIBNAME alias is 8 characters. Once a dataset has been stored in the desired location, the associated alias must be used to retrieve the dataset (without the alias, WPS would look in the default Work directory for the dataset). The following LIBNAME statement assigns the alias mylib to the /mydirectory/ shared directory: LIBNAME mylib '/directories/mydirectory/'; Any directory or database connection that you associate with the alias must already exist before you assign it. For full details of the LIBNAME language element, refer to the WPS Reference For Language Elements guide. Common LIBNAMES can be set up via an AutoExec file so that they do not need to be added to every program that is run. 111

112 As an alternative to using the LIBNAME statement, you can create a new library by either selecting New WPS Data Library from the drop-down next to the New icon in the top left hand corner of the Workbench window, or right-clicking on Libraries in WPS Server Explorer, and then selecting New Library. Set WORK location Proceed as follows to set the pathname for the Work location that is used every time you start up a particular server: 1. In the WPS Server Explorer, Link Explorer, Output Explorer or Results Explorer, ensure that the server is running. 2. Right-click on the server and select Properties from the context menu. 3. In the left hand menu of the Properties dialog, select Startup System Options. 4. On the right of the window, click Add... to display the Startup Option dialog. 5. Click Select... on the right of dialog to see a list of available options in a Select Startup Option window. 6. Search for and/or scroll down to the Work option, and then double-click on it. The Startup Option dialog then displays your selection. 7. in the Value: field, enter the full pathname of your Work folder and then click OK. You will now see the Work option and its associated value listed in the Startup System Options panel of the Properties dialog. 8. When you click OK on the Properties dialog, you will be prompted to restart the server to apply your changes. Any Work option defined in any external Configuration files will be ignored. You must set Work as a Workbench startup option, as described above, in order for it to be used from inside the graphical user interface. When using WPS in Command Line mode to run programs in batch mode, then the startup option is ignored and the Work option in the external configuration file is used instead. Catalogs A catalog is a file in which you can store different types of information (called catalog entries), for example formats, informats, macros, and graphics output. 112

113 As an example, you could write a program to generate a catalog (FORMATS) in which to store PICTURE formats, and another one (SASMCR) in which to store SAS language macros: proc format; PICTURE beau 0-HIGH = ' ' ; PICTURE beaul 0-HIGH = ' ' ; run; proc catalog catalog = work.formats; contents; run; %macro setscalingfactor; %let SCALE=%sysget(SCALE); %if %length(&scale.)=0 %then %let SCALE=2; %mend setscalingfactor; %macro test; %mend; proc catalog catalog = work.sasmacr; contents; run; FORMATS and SASMCR are built into the product for the storage of formats and compiled macros, respectively. Although these catalogs are generated by default in the Work library, you can use the LIBNAME statement to write any catalogs that you wish to keep, to your own permanent directory. The PICTURE statement allows you to create templates for printing numbers by defining a format that allows for special characters, such as leading zeros, decimal and comma punctuation, fill characters, prefixes and negative number representation. For full details of the FORMAT and CATALOG PROCS, and the PICTURE statement, consult the WPS Reference For Language Elements guide. When you run the program, the catalogs are created under the Work folder: To view the entries associated with the catalogs, right-click on them and select Properties. 113

114 Datasets A dataset is a file created or imported by a WPS server, and stored in a library (refer to Libraries). It contains rows and columns, very much like a database table. These rows and columns are known, respectively, as observations and variables in WPS. Observations (rows) usually relate to one specific entity (for example, an order or person). Variables (columns) describe attributes of an entity (for example, an item ID in an order). Table 1. Example Dataset Order ID Item ID Quantity Unit Price In the above example, each observation is an item in the order. The variables are Order ID, Item ID, Quantity and Unit Price. Importing datasets In addition to the datasets created by running programs, datasets can be created by importing data via a WPS server from external files. Currently supported formats are: Delimited Fixed Width Microsoft Excel Spreadsheet Files Important: You can only create datasets in this way on a local WPS Server. The Dataset Import Wizard allows you to configure the dataset as it is imported. It is not always necessary to go through all of the steps in the wizard. You may start the wizard and then, having chosen the file you are importing, simply click Finish to accept all the defaults. Caution: If you import a dataset with the same name as an existing one, you will overwrite it. A warning appears in the wizard if this is going to happen, and you have the chance to change the name of the dataset you are creating. When importing delimited files, the Workbench will attempt to establish automatically which delimiter has been used. If this delimiter is not correct, you will have the option to change it and the preview will be updated to reflect the output that will be generated. 114

115 When importing fixed width files, the Workbench will attempt to determine where columns start and end in the data, although you will have the option to modify these as you wish. Spreadsheet files may contain several worksheets (contained in a workbook). By default, the Workbench will select the first sheet with data for importing. A sheet may also have names that refer to cell ranges, and it is possible to import data from these names, and also from the clipboard. Import of Excel spreadsheet files is also possible via either of the following methods: Programatically using the XLSX or Excel engines. For example: libname xlsxlib XLSX myfile.xlsx HEADER=YES; DATA WORK.IMPORTED; Set xlsxlib.sheet1; Run; /* The above can be generated by the code below */ PROC IMPORT FILE= myfile.xlsx OUT=WORK.IMPORTED DBMS=XLSX; SHEET=Sheet1; Run; Or libname xlsxlib Excel myfile.xls HEADER=YES msengine=ace; DATA WORK.IMPORTED; Set xlslib.'sheet1$'n; Run; /* The above can be generated by the code below */ PROC IMPORT FILE= myfile.xls OUT=WORK.IMPORTED DBMS=Excel; SHEET=Sheet1; Run; You can also use xlsx suffixes with DBMS=Excel. Using the Dataset Import Wizard on Windows local servers (refer to Importing spreadsheet data). In this event, your PC uses the Excel engine (replicating the code used in the second example above), and will therefore need to have the Microsoft ACE OLEDB engine installed in order to be able to read and write Excel files in the XLS or XLSX format. Users who already have Excel installed are likely to have this engine by default. Windows users that do not have Excel installed can download and install the Microsoft Access Database Engine Redistributable. Legacy (XLS) versions of Excel are also supported, and the Import/Export options are available if you have the JET driver installed. However, with the JET driver installed in isolation, you can only read files in XLS format. Importing datasets from files You will need to have the WPS Server Explorer open to be able to complete this task. 115

116 To import files: 1. Right-click the local server and select Import Dataset. The Dataset Import Wizard is launched. 2. Click Change next to the From File text box. 3. Browse to the file that you wish to import. Select it and click Open. A preview of the resulting dataset is shown, for example: 4. Ensure that the appropriate option is selected from the Data Format group for the type of file you are importing. 5. Optional: You can change the name of the new dataset, and where it will be stored, using the controls displayed. 116

117 Change the library in which you want to store your new dataset in by using the Library Name drop-down. Change the name of the dataset from the default by editing the contents of the Member Name field. If you use the name of an existing member, then that member will be overwritten with your new data. 6. Click Next to move to the next page of the wizard. 7. Optional: This page allows you to configure options specific to the type of import you are performing. File Format Configuration Options Delimited The wizard tries to establish the delimiter being used in the file. You can override this as required. Fixed Width The wizard tries to establish the column definitions, but you can also amend these as required. You can define more columns by clicking in a blank area to separate that area into two columns, or you can redefine columns by dragging the existing divisions between them. Dragging a division out of the preview will remove it. Excel The wizard defaults to the import of the first available sheet in the workbook that contains data. If required, choose a different worksheet from the Whole Worksheet drop list. Alternatively, you can select a Named Range from the drop list to use as the data source for importing (if any are available). The preview is updated to reflect any changes you have made. 8. Click Use first row as column headers if you know the first row of the file contains column headers. Examine the preview to determine this. 9. Click Next to move to the last page of the wizard. The Edit Column Properties page is now shown. 10.Optional: You can change the properties of the dataset columns if you wish. You can change a column name by clicking on the column header in the preview and editing the Column Name text box contents. You can change a column data type by clicking on the column header in the preview and changing the Column Data Format option. You can change a column label by clicking on the column header in the preview and editing the Column Label text box contents. 11.Optional: Click Next to see the generated program that will be used to create the dataset. 12.Click Finish to complete the task. The new dataset is imported under the specified Library Name in the WPS Server Explorer. Importing datasets from files using Copy and Paste You will need to have the WPS Server Explorer open to be able to complete this task. 117

118 You can import datasets from files using copy and paste, either from Project Explorer, File Explorer or from outside of the Workbench using your operating system. To start the Dataset Import Wizard by using copy and paste: 1. Highlight the file that you wish to import as a dataset. 2. Either right-click on the file and select Copy, or use the relevant keyboard shortcut (for example CTRL + C). 3. Find the library into which you want to import your dataset, using the WPS Server Explorer. 4. Either right-click the library and select Paste, or use the relevant keyboard shortcut (for example CTRL + V). You will now be on the first page of the Dataset Import Wizard, with the file and library already chosen. You may then click Finish, or proceed with the remainder of the wizard, to fine tune the import. See Importing datasets from files for more on how to use the wizard. Importing datasets from files using Drag and Drop You will need to have the WPS Server Explorer open to be able to complete this task. You can import datasets from files using drag and drop, either from Project Explorer, File Explorer or from outside of the Workbench using your operating system. To start the Dataset Import Wizard by using drag and drop: 1. Highlight the file that you wish to import as a dataset.. 2. Find the library into which you want to import your dataset in the WPS Server Explorer. 3. Drag and drop the file from your source onto the library. You will now be on the first page of the Dataset Import Wizard, with the file and library already chosen. You may then click Finish, or proceed with the remainder of the wizard, to fine tune the import. See Importing datasets from files for more on how to use the wizard. Importing spreadsheet data Provided that your PC has the Microsoft ACE OLEDB engine installed, you can use the Dataset Import Wizard to import range of cells directly from Excel spreadsheets in the XLS or XLSX format. Important: Data imported will have the value it had when the spreadsheet was last saved. If cells are based on formulae, then these are not evaluated by the Workbench when the spreadsheet is opened, with the last saved value in the sheet being used instead. 118

119 Importing datasets from cell ranges using Copy and Paste You will need to have the WPS Server Explorer open to be able to complete this task. You can import a range of cells directly from Microsoft Excel into a Workbench library, as follows: 1. Select the contiguous range in your Excel spreadsheet that you wish to import. 2. Press the keyboard shortcut for Copy (for example CTRL + C). 3. Find the library where you want to import the data and select it in WPS Server Explorer. 4. Press the keyboard shortcut for Paste (for example CTRL + V). You will now be on the first page of the Dataset Import Wizard, with the file and library already chosen. You may then click Finish, or proceed with the remainder of the wizard to fine tune the import. If you click Next instead of Finish, when you reach the Spreadsheet options page, you will notice that the Clipboard contents option is already chosen, and the sheet name and range are displayed. See Importing datasets from files for more on how to use the wizard. Importing datasets from cell ranges using Drag and Drop You will need to have the WPS Server Explorer open to be able to complete this task. You can import a range of cells directly from Microsoft Excel. A cell range can be dragged and dropped onto a library to import only that cell data. 1. Select the contiguous range in your Excel spreadsheet you want to import. 2. Ensure the library you wish to import these cells into is visible in the WPS Server Explorer. 3. Drag and drop the cells onto the library. You will now be on the first page of the Dataset Import Wizard, with the file and library already chosen. You may then click Finish, or proceed with the remainder of the wizard to fine tune the import. If you click Next instead of Finish, when you reach the Spreadsheet options page, you will notice that the Clipboard contents option is already chosen, and the sheet name and range are displayed. See Importing datasets from files for more on how to use the wizard. Opening a dataset You can open a dataset as follows: 1. Ensure that you have the WPS Server Explorer view open ( Window Show View Server Explorer). 119 WPS

120 2. Expand the tree view under the open. Libraries node until you can see the dataset that you wish to 3. Open the dataset in one of two ways: Double-click the dataset. It will open in Browse mode. Right-click the dataset and select either Open (browse) or Edit. Proceed in accordance with Working with the Dataset Viewer. Working with the Dataset Viewer The contents of a dataset are shown in a grid. The rows of the grid represent dataset observations, and the columns represent dataset variables. Tip: You can display labels in the column headers of a dataset that you are viewing in the Workbench. Refer to Dataset Viewer Preferences for more details. You can view, filter and sort a dataset within the viewer. With some datasets, you can also edit observation variables (i.e. cells), remove observations, and also add new observations. If some of the datagrid columns are irrelevant for a task, you can hide them, and you can re-organise the view by moving columns. Refer to Organising the dataset. Mode A dataset is opened in either Browse or Edit mode. By default, a dataset will be in Browse mode unless you specifically ask it to be opened for editing. You can switch between Browse and Edit modes by selecting Data Toggle Edit Mode - refer to Editing a dataset. You can only open a WPS dataset, that is to say a WPD, in Edit mode, and only if nobody else has the same dataset open for editing on another computer. Dataset Viewer Preferences Under Window Preferences WPS Dataset Viewer you can toggle on or off the Show labels for column names option that determines whether or not labels rather than column names are displayed in the column headers of a dataset that is viewed in the Workbench. Toggling on this option assumes that you have already set labels for column names in your programs (some items such as N, MEAN and STD generate labels by default). 120

121 Editing a dataset You can edit observations, and also add and delete them, if the dataset is in Edit mode. Controls for editing a dataset are available from the Data main menu option, from the toolbar, and also from the dataset context menu. If the dataset is open in Browse mode, you can switch to Edit mode by clicking : This Toggle Edit Mode option is also available from the toolbar and from the dataset right-click menu: 121

122 You can make as many changes as you like, and abandon them if you wish to by cancelling them. The changes are not written back to the original dataset until they are saved, by selecting either File Save from the main menu, or Save from the dataset context menu.. At this point, modifications are made, and observations are then deleted and added. If saving your changes fails, then any changes that were not written will remain visible. You will see an error dialog explaining what happened, and details of the failure will be written to the Workbench log. This log can then be used to diagnose the fault. Modifying observations You will need to have a dataset open in Edit mode to complete this task. 122

123 You can edit observation variables (cells) as raw values. If your variables have any formatting applied other than the default, you will not see this during your editing. Once your edit is complete, however, you will see the formatted version. 1. Double click the cell that you wish to edit: 2. Edit the value in accordance with the type of variable: Variable Type Description Numeric You will see the raw value in an edit box. You can simply overtype this with a new value. If you want to see how the value currently in the edit box will be appear as a formatted value, press Shift + F8 and it will be shown as a tooltip. Missing values can be entered as text - refer to Missing values and the editor will preserve them. Numeric (DATE, DATETIME or Dates, DATETIME and TIME values are edited as their respective TIME) types. You can click on any individual element of a date or time (such as a year or hour) in-place, and use the keyboard arrow keys or mouse wheel to increase or decrease them in steps. Numeric elements can also be overtyped with replacement values. For more intuitive control over the edit, you can use the alternative edit control associated with each type. DATE values have a calendar, times have a values have a time picker, and DATETIME DATETIME picker combination. Click on the button to the right of the in-place value and the appropriate editor will appear. 123

124 Variable Type Description String Raw string values can be edited in-place in the same way as numbers. If you want to see how the value currently in the edit box will appear as a formatted value, press Shift + F8 and it will be shown as a tooltip. 3. When you have completed your edits, either press the Enter key or click outside of the cell, to complete the edit. If the value you entered is different from the original saved value, then the observation is considered to have been modified, and will be shown as such. It will appear in bold type with an asterisk (*) next to the observation number in the left margin of the grid. 4. The changes have not actually been saved back to the original dataset at this point. To Save the changes and write them back to the server, select either File Save from the main menu, or Save from the dataset context menu. Deleting observations You will need to have a dataset open in Edit mode to complete this task. To delete observations from a dataset: 1. Select the observation that you wish to delete by clicking on its observation number in the left hand column. If you wish to delete multiple observations, hold down the CTRL key while clicking on the observation number of each one that you wish to delete. The selected observations are highlighted. 2. Select Delete Observation, from the Data main menu option, the toolbar, or the right-click menu on the dataset. A message appears asking you to either confirm the deletion or cancel it. 3. Click Yes to confirm the deletion. The data in the cells will be lightly crossed out, and a minus character (-) will appear next to the row numbers in the left margin, to indicate that the observations are marked for deletion: 124

125 4. The changes have not actually been saved back to the original dataset at this point. To Save the changes and write them back to the server, select either File Save from the main menu, or Save from the dataset context menu. Adding observations You will need to have a dataset open in Edit mode to complete this task. New observations can be added to a dataset. They are always added to the end of the dataset, regardless of your current position within it. To add a new observation: 1. Select Add Observation, from the Data main menu option, the toolbar, or the right-click menu on the dataset. 2. The new row will appear in bold type, and a plus character (+) will appear next to the observation number in the left margin of the grid, to indicate that the row is new. You can now edit the new observation in order to populate the variables as required. 3. The changes have not actually been saved back to the original dataset at this point. To Save the changes and write them back to the server, select either File Save from the main menu, or Save from the dataset context menu. Cancelling changes You can cancel any changes that you have made but not yet saved. 1. Select dataset. Cancel edits, from the Data main menu option, the toolbar, or the right-click menu on the The Confirm Cancel Edits dialog will appear. 2. Click Yes to confirm. 125

126 3. Any unsaved edits that you have made are cancelled, returning the dataset to how it was before the changes were made. Missing values You will need to have a dataset open in Edit mode to complete this task. You can set observation variables to missing by using the Set Missing option in the datagrid context menu. When numeric variables are formatted as DATE, DATETIME or TIME, this is the only way to set these variables as missing. 1. Select the observation variable (cell) you want to set as missing. Ensure that only one variable is selected. You cannot set several observation variables to missing in a single operation. 2. Right-click on the dataset to display the context menu. 3. Select Set Missing. 4. The Workbench will respond to your command in one of two ways, depending on the variable type. Variable Type Description Numeric The Set Missing Value dialog opens. If the observation variable is already set to a missing value, then the current raw value is shown - otherwise, the missing value defaults to '.' (full stop). You can change the missing value by simply pressing the key that corresponds to the value you want to set. This value can be any of the following:. (full stop),._ (full stop followed by an underscore), and.a to.z. Press Enter or click OK to complete the command. Press Escape or click Cancel to return to the grid with the original value unchanged. String String variables are simply set to a single space (' ') character when this option is chosen, and no dialog appears. 5. The changes have not actually been saved back to the original dataset at this point. To Save the changes and write them back to the server, select either File Save from the main menu, or Save from the dataset context menu. Filtering a dataset This is only possible on a dataset that is on a WPS server version 3.2 or later. (The version of your server is displayed in the Properties view when you select the server in the WPS Server Explorer.) 126

127 Filters can be applied to a dataset regardless of the mode in which it is opened. You can filter the contents of the dataset by variable, so that you see only the data that you need. Filters are cumulative. Therefore, if you filter on more than one variable, all the various filters will apply. You can cancel any of the filters at any time. It is still possible to add an observation to a dataset while a view is being filtered. The new observation will be visible during editing, regardless of the contents of the filtered variables. As soon as the changes to the dataset are saved, any filters are applied, and so the new observation will disappear from view if it no longer meets the active criteria. To filter your dataset view: 1. Click the filter button below the variable heading for the column that you wish to filter. The filter criteria menu is shown: 2. Select the criteria by which you wish to filter the view. Depending on the variable and the criteria chosen, either the filter button is replaced by an edit box below the variable header (numeric and string values), or a dialog with calendar/time controls is displayed. 3. Complete the criteria for the filter by entering the appropriate details. 127

128 Data Type Criteria DATE, DATETIME or TIME Most expressions based on a date or time variable are set in another dialog. Use the calendar and clock controls to set the date criteria. For DATETIME values, click the button to set the time component of the filter value. Other numeric The expression for the filter is shown below the variable header. Enter the value or or string values necessary to complete the expression in the edit box. For example, to filter on a numeric variable to show only observations that are less than 100: LT 100 For a more complete list of the expressions that can be entered, see the reference section Dataset filter expressions. Once the filter is applied, the filter button icon will change from to, indicating that the variable is now used in a filter. 4. Optional: You can now set any further filter criteria on other columns by following the steps above. 5. Optional: You can clear the filter for a variable by clicking on the filter button selecting again, and then Clear Filter. As you apply and cancel filters, the dataset contents are updated automatically in accordance with the latest set of criteria. Dataset filter expressions You can filter the data viewed in a dataset. The filter menu options are essentially shortcuts to preparing a filter expression to use when the server is queried for the dataset data. If the observation on which the filter is based is not a DATE, DATETIME or TIME formatted variable, you can edit the filter expression that is generated. Choosing to filter on these variables from the menu will start the expression, and leave the cursor ready for you to enter a value to filter by, if one is needed. You can then amend this filter by clicking on the expression and editing it. You cannot edit the expressions of DATE, DATETIME or TIME variable filters. These can only be cleared and re-entered. The table below shows the editable expression syntax that is available from the filter menu. Filter Expression Syntax Criteria Equal to Expression Examples EQ x or EQ s Is equal to 100 (numeric) EQ

129 Criteria Expression Examples Is equal to "Blanco" (string) EQ "Blanco" Not equal NE x or NE s to Is not equal to 100 (numeric) NE 100 Is not equal to "Blanco" (string) NE "Blanco" Less than LT x Is less than 100 LT 100 Greater GT x than GT 100 Less than LE x or equal to Greater GE x Is greater than or equal to 100 GE 100 BETWEEN x AND y (inclusive) Not Is less than or equal to 100 LE 100 than or equal to Between Is greater than 100 Is between 100 and 200 BETWEEN 100 AND 200 NOT BETWEEN x AND y between (inclusive) Is not between 100 and 200 BETWEEN 100 AND 200 Is missing IS MISSING IS MISSING Is not IS NOT MISSING IS NOT MISSING IN ( x, y ) or IN ( s1, s2 ) Is one of the values 100, 200 or 300 missing In IN (100,200,300) Is one of the values "Blanco", "Jones" or "Smith" IN ("Blanco","Jones","Smith") Starts with LIKE " s% " Starts with the string "Bla" LIKE "Bla%" Ends with LIKE " %s " Ends with the string "nco" LIKE "%nco" 129

130 Criteria Contains Expression Examples LIKE " %s% " Contains the string "an" LIKE "%an%" Sorting a dataset This is only possible on a dataset that is on a WPS server version 3.2 or later. (The version of your server is displayed in the Properties view when you select the server in the WPS Server Explorer.) Sorting is not available if the dataset is open in Edit mode. You can sort the contents of a dataset on several variables. Variables that are part of an active sort have an icon representing the direction of the sort in the header. The size of the icon indicates the significance of the variable in the sort. The the secondary key, and the or or icon represents the sort primary key, the or icon the tertiary and subsequent keys. If you attempt to switch to Edit mode while a sort is currently active, a warning will be displayed. This is because to go into Edit mode would require the entire dataset to be rewritten in accordance with the current sort order, to allow it to be edited in-place. If you require this, click Yes in the dialog, but you must be aware that this will re-write the entire dataset on the server in the order you have set in the grid, and put the grid into Edit mode. If you do not required this, click No. You can sort a dataset as follows: 1. Right click the column header for the variable that you wish to use as the primary key. The column header menu will appear. 2. Click on either Ascending Sort or Descending Sort to perform the sort. The grid data is now sorted in the order requested. 3. Optional: You can now add secondary and subsequent keys to the sort by following the steps above. 4. Optional: You can clear any of the sorts by using the Clear Sort option from the context menu for the associated variable. Organising the dataset You can manipulate the view of the dataset so that you hide variables you do not need, and move columns so that they are in a different order. These changes only affect your view of the data and do not affect the data itself. 130

131 Hiding variables To hide a datagrid column: 1. Right-click the column header for the variable you want to hide. The context menu appears. 2. Click Hide column(s). The datagrid column disappears from the view. If you attempt to hide a column for which filtering is currently active, then you will be asked to confirm that you wish to remove the filtering and hide the column. Click Yes or No as appropriate. Showing hidden variables To show previously hidden dataset variables: 1. Right-click the dataset header row. The context menu appears. 2. Click Show / Hide Columns... The Show / Hide Columns dialog appears, showing check boxes for the displayed columns (these are ticked), and for the hidden columns (these are not ticked). 3. To show a column that was previously hidden, tick its check box. 4. Click OK. The columns displayed now reflect the changes made in the Show / Hide Columns dialog. Moving columns You can move columns to wherever you wish within the dataset view, regardless of the order of the columns in the actual dataset. Doing this will not change the physical order of the columns on the server, only your current view of them. To move a column: 1. Left-click and hold the mouse button down on the column header. 2. With the mouse button still held down, drag the column towards where you would like it to be. As you drag the column left or right, the column header will become translucent. You will see a thick grey line appear between columns, indicating where the column will appear if you release the left mouse button: 131

132 3. Release the left mouse button when the grey line is in the correct place. The column appears in the new position. Exporting datasets WPS datasets can be exported under Windows as delimited and fixed width text, and also as Microsoft Excel spreadsheets. The Dataset Export Wizard allows you to fine tune the contents of export file as required. To export a dataset: 1. Find the dataset you want to export in the WPS Server Explorer. 2. Right-click the dataset and select Export Dataset. The Dataset Export Wizard is launched. 3. Select Delimited, Fixed Width or Excel as required. For Excel, select which Excel format is to be used, from the drop-down. For Delimited or Fixed Width, the Export preview pane shows how the first few lines of the file will appear in the export. 4. Click Next. 5. Optional: You can further configure Delimited and Fixed Width export. If you wish to include the names of the columns, select the Include field names on first row check box. Further configuration options depend on the export type: Export Type Options Delimited Click on the delimiter of your choice, or click Other and type your own in the box provided, if none of the standard delimiters are suitable. Fixed Width Alter the width of the columns by selecting the column in the drop-down, and editing the Start and Width values. 132

133 Any changes you make here are reflected in the Export preview. Click Next when you are ready to move on to the next step. 6. Optional: The default filename is shown, along with the path. You can edit this if you wish, and Browse is available to allow you to find a suitable location for the exported file. 7. To open the file once the export is complete, ensure that Open when complete is selected. If the Workbench cannot open the file, it will be opened in the appropriate application for your operating system. 8. If the file already exists, the Confirm replace option will be available, and you will be unable to continue unless it is checked. You can also select the Always replace option, so that the Workbench will always replace any existing files automatically and just warn you instead. This is useful if you want to export to the same file several times in the same Workbench session. 9. Optional: Click Next to see the WPS program that the Workbench will run via the server to perform the export. 10.Click Finish. If you asked for your file to be opened when the export is complete, it may open in the Workbench (depending on the file extension associated with the export file). Clearing datasets You cannot just clear the datasets on their own. The process for clearing datasets unavoidably means that you also end up clearing all the other output, such as the HTML output, listing output, log entries, libraries, file references, and so on. In order to clear all the output, proceed as in Restarting the server. 133

134 Running programs You can run a program from either inside the Workbench or a command line outside of the Workbench. To see how you can control the output (datasets, logs, results, and so on) generated from the execution of a program on the selected server, refer to Working with program output. For details about some of the settings related to the running of programs, refer to WPS Preferences for running programs. All libraries, datasets and macro variables are persistent. This means that, once they are assigned during the execution of a program, they are available to other programs that are run during the same Workbench session. WPS Preferences for running programs To control the general behaviour of WPS Workbench during program execution, make the appropriate selections from the following, under Window Preferences WPS, before running any programs: Save all modified files before running a program This setting controls whether WPS will save any modified programs before a program is run. The behaviour can be one of : Always, Never or Prompt. The default is Prompt, which causes the Save and Run dialog to be displayed whenever you attempt to run a program that is not saved. When you are editing a program and execute it using the Run button, it is the current content of the editor window that is submitted, and not the contents of the file, and so if, for example, the setting is Never, these unsaved changes in the editor window will always be executed. The Save and Run dialog gives you some control and allows you to switch the setting to Always (or Never) if you feel that this is more appropriate. For example, you might want to switch the setting to Always if you have a program that is built up from several source files. You might have one source file using an %INCLUDE statement to include the contents of the second, where the %INCLUDE statement reads the contents of the second file exactly as they appear on disk (and not from the current content of the editor window). In this event, you would always want your edits to be saved to disk, to ensure that they are executed. Close all open datasets before running a program This setting controls how WPS deals with closing open datasets when running a program. The behaviour can be one of: Always, Never or Prompt. The default is Prompt, which causes the Save and Run dialog to be displayed whenever you attempt to run a program when one or more datasets is open. 134

135 Having a dataset open in the Dataset Viewer (refer to Working with the Dataset Viewer) can cause problems if you attempt to run a program that is going to overwrite this same open dataset with a new version. For this reason, you may want to set this option to Always, to avoid such problems. Show log when an error is encountered running a program This setting controls whether WPS shows the log file when an error is encountered in a program. The behaviour can be one of: Always, Never or Prompt. The default for this option is Prompt which causes the Confirm Log Display dialog to be shown the first time an error is encountered during the running of a program. If you leave Remember my decision ticked, then: Selecting Yes in the Confirm Log Display dialog will cause the setting to switch to Always, so that the log is shown automatically whenever there is an error. Selecting No in the Confirm Log Display dialog will cause the setting to switch to Never, so that the log is not shown automatically whenever there is an error. Close all open datasets when deassigning a library This setting controls whether WPS automatically closes any datasets that may be open in a library when you deassign a library by selecting the Delete item from the context menu in the WPS Server Explorer. The behaviour can be one of: Always or Prompt. The default for this option is Prompt which causes a dialog to be displayed when you attempt to deassign a library with open datasets. Confirm deletions This setting controls whether or not WPS asks for confirmation when you use the from the context menu in the Delete item WPS Server Explorer to take one of the following actions: delete a server definition delete a dataset, catalog or view from within a library de-assign a library de-assign a Fileref delete a catalog entry from within a catalog. Confirm server restart This setting controls whether or not WPS asks for confirmation when you select a server in the WPS Server Explorer and then select Restart from the context menu. Autoscroll the log This setting controls whether or not WPS automatically scrolls the log output (refer to Viewing the log). Autoscroll the listing This setting controls whether or not WPS automatically scroll the listing output (refer to Viewing the listing output). 135

136 Show advanced server actions This setting controls the context menu options available when restarting WPS servers (refer to Restarting with Advanced Server Actions). Temporary file location This field points to the directory where the Workbench stores temporary files. The log files created during execution of a program are stored in this directory, as are any ODS HTML results generated by programs. You should be aware that output files, particularly logs, can be sizeable, and so may find that you need to modify this setting if the field points by default to a location with space restrictions. You may also wish to set Always Run in Background (refer to General Preferences) if you are going to be running programs that take a long time to execute. Running a program from inside the Workbench The Workbench can only run one program at a time on each WPS server. This means that, if a program is running and you attempt to run another one on the same server, that program will be queued and will not be executed until the other program has been completed. You may, however, register more than one WPS server, in which case you can have more than one program running concurrently. To run a program from inside the Workbench: 1. Ensure that the Code Submission option is set appropriately on the server (refer to Local WPS server properties or Remote WPS server properties as appropriate). 2. Select the program you want to run by using one of the following methods: Highlight the Ensure that the program to be run in either the Project Explorer or File Explorer. program to be run is open in the Editor and is active. If the program was already open and you have part of the program highlighted, then the selected part will be executed (not the whole program). 3. Execute the program by doing one of the following: Use the CTRL + R keyboard shortcut to run the program on the default WPS server. From the toolbar, click the button to run the program on the default server, or click the dropdown next to this button to select a non-default server. From the main menu, select WPS Run File <pathname> Local Server (or substitute the name of your remote WPS server in place of Local Server). 136

137 From the program's context menu, select Run On Local Server (or substitute the name of your remote WPS server in place of Local Server). When the program is run, an Executing window opens (unless Always Run in Background is selected), and its progress is indicated in the bottom right hand corner of the Workbench. When you run a program, the state from previous executions is preserved, so that subsequent executions can interact with the datasets, Filerefs, and so on, that have been previously created. In order to clear previous output on a given WPS server, select, from either the WPS menu or toolbar, Clear Log Local Server (or substitute the name of your remote WPS server in place of Local Server), or Clear Results Local Server (or substitute the name of your remote WPS server in place of Local Server). Alternatively, to clear the state of a WPS server completely, thereby emptying the Work library and de-assigning all of the macro definitions and libraries, then either select WPS Restart Server Local Server (or substitute the name of your remote WPS server in place of Local Server), or right-click the server in WPS Server Explorer and select Restart. Refer to Restarting the server. Running part of a program You can execute a particular part of a program as follows: 1. Ensure that the relevant program is open and active. 2. Highlight the section of code within the program that you wish to execute. 3. Execute the portion of code by doing one of the following: Use the CTRL + R keyboard shortcut to run the code on the default server. From the toolbar, click the button to run the code on the default server, or click the drop-down next to this button to select a non-default server. From the main menu, select WPS Run selected code from <pathname> Local Server (or substitute the name of your remote WPS server in place of Local Server). From the program's context menu, select Run On Local Server (or substitute the name of your remote WPS server in place of Local Server). Right-click in the Editor and select Run On Local Server (or substitute the name of your remote WPS server in place of Local Server). While the program is being executed, its the Workbench. progress is indicated in the bottom right hand corner of 137

138 Stopping an execution If a program is running and you want to stop it before it has finished executing, proceed as follows: 1. From the main menu, either select WPS Cancel Local Server (or substitute the name of your remote WPS server in place of Local Server), or click in the Progress view. 2. Once the progress indicator in the lower right corner of the Workbench disappears, this indicates that the program has stopped running. Depending on the particular step that the program is executing, the program may not stop immediately after you try and stop it. The log will contain a message similar to ERROR: Execution was cancelled. WPS in Command Line mode Besides being able to use WPS in Workbench mode (that is to say, from the graphical user interface), you can also use it in Command Line mode, where it is referred to as wps. This provides a way of running programs outside of the Workbench, which is also referred to as running in 'batch mode'. In this mode, you cannot compile programs into run-time jobs. To use WPS from a command line, you need to execute wps.exe (or simply wps) on Windows, or wps on any of the UNIX-based platforms. This executable file is located in the bin directory of your WPS installation, and so you should switch to this directory first. Refer to Running a program from the command line of a Windows platform and Running a program from the command line of a non-windows platform for examples. Options Running wps.exe or wps on its own will not do anything, and so you will need to pass some additional instructions in the following form: wps.exe <options> <programfilename> The <options> that are called from the command line can be a list of any of the following: -optionname [optionalvalue] -config <configfilename> -set <envvarname> <envvarvalue> 138

139 When you run a program using wps.exe or wps, the <programfilename> must always be the last parameter you define. (When wps is executed, the first parameter that is encountered which does not start with a dash (-) is taken as the name of the program to run.) The WPS compiler/interpreter is invoked directly. The files from the Results output cannot be seen inside the Workbench, unless the resulting files are opened manually inside it. System options To set a system option explicitly, specify: wps.exe -optionname [optionalvalue] <programfilename> You can pass as many optionname system options to wps as you wish. However, you can only pass wps single value options. The command line does not allow parentheses. You can quote values with spaces in, but the quotes will be removed. Configuration files System options can be defined in a configuration (config) file, and this file can be explicitly referenced when executing wps: wps.exe -config <configfilename> <programfilename> Refer to the Configuration files section for a more detailed discussion about configuration files and the order in which they are processed. Important: When running programs using wps, any WPS server properties that have been set up as preferences under the graphical user interface, are ignored. Environment variables To set an environment variable to use with wps: wps.exe -set <envvarname> <envvarvalue> <programfilename> You can set as many environment variables as you want but remember that, as above, wps only allows single values in the command line, and it does not allow parentheses. Log output When you run a program with wps, the log information about the run is automatically sent to the command window in which WPS is running. Once the program has finished running and this window closes, then this log information is lost. To capture this log information in Windows and non-windows environments (optionally using batch files and shell scripts, respectively), refer to Running a program 139

140 from the command line of a Windows platform and Running a program from the command line of a nonwindows platform. Results output When a program is run using wps, any results generated by the program are automatically captured into a file called <programfilename>.lst created in the same directory as the program. For example, a file called Program1.lst will be output if you run a program called Program1.sas. You can open the results file with the text editor of your choice. Running a program from the command line of a Windows platform Refer to WPS in Command Line mode for details about the <options> that can be specified. Example Let us assume that you wish to run a program called Program1.sas located in the directory D:\Work \WPS Programs. Open a command window and change to the \bin directory of the WPS installation, and then, following the prompt, enter the following command: wps.exe "D:\Work\WPS Programs\Program1.sas" Creating a batch file to call WPS If you wish to be able to run one or more programs using the same options each time, then it is advisable to create a batch file to do this for you. For example, if WPS is installed in C:\Program Files\World Programming WPS 3, and your program is located in directory d:\work\wps Programs, then you could create a batch file called RunPrograms.bat containing the following lines: set WPSLOC=C:\Program Files\World Programming WPS 3 set PRJLOC="D:\Work\WPS Programs" "%WPSLOC%\bin\wps" "%PRJLOC%\Program1.sas" Ensure that absolute (fully qualified) paths are specified so that they can be executed from anywhere on your machine and still work. 140

141 Including log file output in the batch file When running wps, it is useful to capture the log information so that you can verify whether any errors or problems were encountered. To do this, redirect the output of the program to a file. For example, to modify the above example to redirect the output to a file called Program1.log, change the example code to: set WPSLOC=C:\Program Files\World Programming WPS 3 set PRJLOC="D:\Work\WPS Programs" "%WPSLOC%\bin\wps" "%PRJLOC%\Program1.sas" > "d:\work\wps Logs\Program1.log" Once the batch file is run, the file Program1.log will be in the specified directory and can be opened with the text editor of your choice. Every time that you capture the log information into a file with the same name, the file will be recreated. In other words, log information is not appended to the same file - it only shows details from the latest run. If you do require the new log to be appended, change the redirection symbol > to >>, for example: "%WPSLOC%\bin\wps" "%PRJLOC%\Program1.sas" >> "d:\work\wps Logs\Program1.log" Tip: Because log files can be too large to scan with the human eye to find individual errors, a simple search for error will verify whether or not the program was executed correctly. Running a program from the command line of a non-windows platform Refer to WPS in Command Line mode for details about the <options> that can be specified. Example Let us assume that you wish to run a program called Program1.sas located in the directory /home/ user/programs. Open a command window and change to the /bin directory of the WPS installation, and then enter the following command: wps "/home/user/programs/program1.sas" Creating a shell script to call WPS If you wish to be able to run one or more programs using the same options each time, then it is advisable to create a shell script to do this for you. 141

142 For example, if WPS is installed in the directory /tools/wps and your program is located in directory /home/user/programs, then you could create a script called RunPrograms.sh containing the following lines: export WPSLOC=/tools/wps export PRJLOC=/home/user/programs "$WPSLOC/bin/wps" "$PRJLOC/Program1.sas" The script will need the correct permissions in order to be executable. Including log file output in the shell script When running wps, it is useful to capture the log information so that you can verify whether any errors or problems were encountered. To do this, redirect the output of the program to a file. For example, to modify the above example to redirect the output to a file called Program1.log, change the example code to: export WPSLOC=/tools/wps export PRJLOC=/home/user/programs "$WPSLOC/bin/wps" "$PRJLOC/Program1.sas" > "/home/user/logs/program1.log" Once the shell script is run, the file Program1.log will be in the specified directory and can be opened with the text editor of your choice. Every time that you capture the log information into a file with the same name, the file will be recreated. In other words, log information is not appended to the same file - it only shows details from the latest run. If you do require the new log to be appended, change the redirection symbol > to >>, for example: "$WPSLOC/bin/wps" "$PRJLOC/Program1.sas" >> "/home/user/logs/program1.log" Tip: Because log files can be too large to scan with the human eye to find individual errors, a simple search for error will verify whether or not the program was executed correctly. 142

143 Working with program output Output from programs is generated in the following views: WPS Server Explorer - Provides access to the datasets, catalogs, Filerefs, and so on, that have been generated under the relevant libaries (for example, the default Work library) for the particular server. Refer also to Dataset generation. Output Explorer - Provides access to the listing output, HTML output, logs generated by the Workbench's ODS (Output Delivery System). listing output, PDF output and Results Explorer - Provides access to hierarchical lists of the and PDF output. HTML output Outline (of structural elements) - Provides access to the structural elements from the programs, logs, listing and HTML that have been output. If you click on a structural element in this view, the relevant line in the particular output file will be highlighted. Log output for a server is cumulative and, as such, shows information and errors from each program that has been run during the current session. It can be cleared in accordance with Clearing the log. Listing output is also cumulative and shows the results of every program that has been executed during the current session. HTML output similarly shows the results of programs, but is not cumulative. Listing and HTML output can be cleared in accordance with Clearing the results output. The server itself can also be restarted in accordance with Restarting the server. This will clear the log as well as any listing and HTML output. It will also delete any temporary files and deassign all libraries, datasets and macro variables, and so on, that may have been set up on the server. Dataset generation If your program produces or amends a dataset, then this can be viewed from the relevant library in WPS Server Explorer. For example, each time you run the following sample program, having amended the bookmarked line as required, the associated dataset is updated in the Work library: 143

144 For more information about the use of libraries on a server, refer to Libraries. For details about viewing datasets, and manually amending them as required, refer to Working with the Dataset Viewer. To view the details associated with a particular dataset, right-click on the dataset in the above view and select Properties. 144

145 Managing ODS output Once you have run a program that produces some output using the Workbench's ODS (Output Delivery System), you can view it in the Results Explorer. The ODS destinations (which can be thought of as output formats in the context of WPS Workbench), and the location of the output generated, can either be managed yourself, using explicit ODS statements in your code, or left to the Workbench to manage automatically. Result Options Preferences By default, WPS controls results automatically, in accordance with the setup in Window Preferences WPS Result Options: 145

146 The default Yes setting of Automatically Manage Result Types causes ODS destinations to be created automatically, in accordance with the check boxes ticked in the Result Types panel (both HTML and Text (LISTING) output, accessible via the Output Explorer, are set initially). WPS creates the destinations by automatically injecting relevant ODS statements before and after each program is submitted (these statements are shown in the log automatically if Show generated injected code in the log is selected). If you select PDF, then, the first time that you execute a program, the PDF destination appears in the Output Explorer and Results Explorer. Even if automatic management is chosen, it is still possible to define custom ODS destinations using explicit ODS statements in your code. You can set up your own HTML and PDF output within the program code and/or via WPS Code Injection. For a PDF program code example, refer to PDF output. If Automatically Manage Result Types is set to No, then no ODS destinations will be set up by default, and all the output from running programs will be sent by default to the Text (LISTING) destination. This behaviour reflects what happens when you run WPS in Command Line mode, which requires programs to control their own ODS destinations. Logs This section of the guide looks at the management of the Output Explorer. log output that is displayed in the If you have more than one WPS server registered in the Workbench, then a separate log is available for each server in the Output Explorer. Log Colouring Preferences The preferences that you can set regarding the different items contained in a log file (errors, notes, warnings, and so on) are found under Window Preferences WPS Log Syntax Coloring: 146

147 For each different type of item contained in a log, you can specify attributes for Colour, Background Colour, and whether or not the item should be displayed in Bold. Viewing the log To display the information contained in the log: 1. Ensure that you have the Explorer). Output Explorer open ( Window Show View Output 2. If there is more than one server, open the required server node to display the associated log. 3. Either double-click the Log node, or right-click it and select The log opens and is given focus. 147 Open from the context menu.

148 If you have performed several runs of a program, the previous log information will be concatenated into the existing log text. If you wish to clear the log, to ensure that when you next run a program the log only contains information for that run, then you can proceed in accordance with either of the following: Clearing the log. Restarting the server (which will clear the log and all results, datasets, library and Filerefs). If the log contains a large amount of information, refer to Navigating the log. Tip: You can control how the different items (errors, notes, warnings, and so on) are displayed in a log. Refer to Log Colouring Preferences. Navigating the log If you have executed several programs, or several instances of the same program, and have not cleared the log for the particular server by either Clearing the log or Restarting the server, then each instance of output will have been appended to the log in order of execution. To navigate the information contained in the log file: 1. Open the log in accordance with Viewing the log. 2. Ensure that you have the Outline view open (Window Show View Outline). 3. In this view you will see nodes for all the previous log entries with the times at which they were created. You may also see error or warning nodes. Click on any of these nodes and the corresponding section in the log file will be displayed. Saving the log to a file To save the log to a file: 1. Ensure that you have the Explorer). Output Explorer open ( Window Show View Output 2. Do one of the following: Log node, and, from the context menu, select Save As... Right-click on the Open the log in the editor (see Viewing the log), and then right-click in the editor window and select Save As. Open the log in the editor and then select File Save As... from the main menu. 3. Use the Save As dialog to save the file to the required location. 148

149 Printing the log To print the log for a particular server: 1. Ensure that you have the Explorer). Output Explorer open ( Window Show View Output 2. If there is more than one server, open the required server node to display the associated output. 3. Do one of the following: Log node, and, from the context menu, select Print Log... Right-click on the Open the log in the editor (see Viewing the log), and then right-click in the editor window and either select Print or press Ctrl+P on Windows (Cmd-P on MacOS). Open the log in the editor and then select File Print... from the main menu. 4. Use the Print dialog to send the log to your required printer. Clearing the log 1. If you wish to save a log before clearing it, proceed as in Saving the log to a file. 2. Clear the contents of the log for the required server by doing one of the following: From the main menu, select WPS Clear Log Local Server (or substitute the name of your remote WPS server in place of Local Server). Use the keyboard shortcut Ctrl + Alt + L to remove the log from the default server. If you have more than one WPS server registered, then the above action will clear the log for the Default WPS server. If in doubt as to which is the default server, use the tooltip for the toolbar button to show which log will be cleared. From the toolbar, click to clear the log from the default server, or click the drop-down to this button to select a non-default server. Ensure that you have the Output Explorer open ( Window Show View Output Explorer), right-click on the Log node for the required server, and from the context menu, select Clear Log. The log file for the selected server will now be blank. PDF output This section of the guide looks at the PDF output of results. To set up the automatic management of PDF output, refer to Result Options Preferences. 149 next

150 The default settings for PDF output are as specified in the wps.cfg file (refer to Configuration files), and are as follows: -BOTTOMMARGIN 1cm -LEFTMARGIN 1cm -RIGHTMARGIN 1cm -TOPMARGIN 1cm -ORIENTATION portrait The PAPERSIZE is determined automatically by the locale of WPS Workbench (refer to WPS server LOCALE and ENCODING settings). It can be reset using unmanaged output (see below). The startpage option, which determines whether or not the output from each PROC starts on a new page, is not configurable inside WPS Workbench. It is initially set to STARTPAGE=yes in the ODS software, which means that each PROC does start on a new page. The option can also be reset using unmanaged output (see below). You create unmanaged output by entering code directly into your programs, as per the example below: options orientation=landscape; options papersize=a4; options topmargin=0.75in; options bottommargin=0.5in; options leftmargin=0.5in; options rightmargin=0.5in; ods pdf file="body.pdf" startpage=no; /* Startpage=no means that new pages are not generated between PROCs /* Insert PROCs to generate output */ ods_all_ close; */ Relevant parts of the code can also be used as WPS code injections. Listing output This section of the guide looks at the listing output of results. Listing Colouring Preferences The preferences that you can set regarding the different items contained in listing results are found under Window Preferences WPS Listing Syntax Coloring: 150

151 For each different type of item contained in a listing, you can specify attributes for Colour, Background Colour, and whether or not the item should be displayed in Bold. Viewing the listing output To view the listing output: 1. Ensure you have the Output Explorer open ( Window Show View Output Explorer). 2. If there is more than one server, open the required server node to display the associated output. 3. Either double-click the Listing node, or right-click it and select The listing output opens and is given focus. 151 Open from the context menu.

152 If you have performed several runs, the previous listing output will be concatenated into the existing results. If you wish to clear the output, to ensure that when you next run a program the listing only contains results for that run, then you can proceed in accordance with either of the following: Clearing the results output (which will also clear any HTML output). Restarting the server (which will clear the log and all results, datasets, library and Filerefs). Navigating the listing output If you have executed several programs, or several instances of the same program, and have not cleared the results for the particular server by either Clearing the results output or Restarting the server, then each instance of listing output will have been appended to the existing listing file in order of execution. To navigate the output contained in the listing file: 1. Open the results in accordance with Viewing the listing output. 2. Ensure that you have the Outline). Outline (of structural elements) view open ( Window Show View 3. In this view you will see nested output for the various programs, with nodes for the different output elements. Click on any of these nodes and the corresponding section in the listing file will be displayed. Saving the listing output to a file To save the listing output to a file: 1. Ensure that you have the Explorer). Output Explorer open ( Window Show View Output 2. Do one of the following: Listing node, and, from the context menu, select Save As... Right-click on the Open the listing in the editor (see Viewing the listing output), and then right-click in the editor window and select Save As. Open the listing in the editor and then select File Save As... from the main menu. 3. Use the Save As dialog to save the file to the required location. Printing the listing output To print the listing output for a particular server: 152

153 1. Ensure that you have the Explorer). Output Explorer open ( Window Show View Output 2. If there is more than one server, open the required server node to display the associated output. 3. Do one of the following: Listing node, and, from the context menu, select Print Results... Right-click on the Open the listing in the editor (see Viewing the listing output), and then right-click in the editor window and either select Print or press Ctrl+P on Windows (Cmd-P on MacOS). Open the listing in the editor and then select File Print... from the main menu. 4. Use the Print dialog to send the results to your required printer. HTML output This section of the guide looks at the HTML output of results. Viewing the HTML output To view the HTML output: 1. Ensure you have the Output Explorer open ( Window Show View Output Explorer). 2. If there is more than one server, open the required server node to display the associated output. 3. Either double-click the HTML node, or right-click it and select Open from the context menu. The HTML output file opens and is given focus. Navigating the HTML output If you opted to have the HTML output automatically managed by the Workbench (refer to Result Options Preferences), then each run will create a new HTML file. However, if you have executed several programs, or several instances of the same program, and have not cleared the results for the particular server by either Clearing the results output or HTML output will still be available in the Restarting the server, then the previous Outline (of structural elements) view. To navigate the output contained in the HTML file: 1. Open the results in accordance with Viewing the HTML output. 2. Ensure that you have the Outline). Outline (of structural elements) view open ( Window Show View 153

154 3. In this view you will see nested output for the various programs, with nodes for the different output elements. Click on any of these nodes and the corresponding section in the HTML output will be displayed. Printing the HTML output To print the HTML output: 1. Ensure that you have the Explorer). Output Explorer open ( Window Show View Output 2. If there is more than one server, open the required server node to display the associated output. 3. Do one of the following: HTML node, and, from the context menu, select Print Results... Right-click on the Open the HTML file in the editor (seeviewing the HTML output), and then right-click in the editor window and either select Print or press Ctrl+P on Windows (Cmd-P on MacOS). Open the HTML file in the editor and then select File Print... from the main menu. 4. Use the Print dialog to send the results to your required printer. A single HTML output file is created for each run within the Workbench. However, you can only print the HTML output of one run at a time. Clearing the results output 1. If you wish to save your output before clearing it, save your PDF elsewhere if you have been using the PDF destination, or proceed as in Saving the listing output to a file. 2. Clear the output results for the required server by doing one of the following: From the main menu, select WPS Clear Results Local Server (or substitute the name of your remote WPS server in place of Local Server). Use the keyboard shortcut Ctrl + Alt + O to remove the results from the default server. If you have more than one WPS server registered, then the above action will clear the results for the Default WPS server. If in doubt as to which is the default server, use the tooltip for the toolbar button to show which server's results will be cleared. From the toolbar, click to clear the results from the default server, or click the drop-down next to this button to select a non-default server. 154

155 Ensure that you have the Output Explorer open ( Window Show View Output Explorer), right-click on the listing output, HTML output or PDF output for the required server, and from the context menu, select Clear All Results. All output will now be blank. The effects of this option are different from Restarting the server in that you preserve the context of what you are currently doing, and do not lose your temporary work. Restarting the server Each time that the Workbench is closed, the results associated with the session - the log, all the output results, the Filerefs, libraries and datasets, and so on - are cleared. However, if you wish to clear the same things prior to the end of the Workbench session, then you can do so by restarting the WPS server, as shown below. Caution: Doing this means that programs will no longer be able to interact with any objects created prior to the restart of the server. If you only wish to clear the log or results, and keep all the other output, then proceed as in Clearing the log or Clearing the results output respectively. Proceed as follows to restart the server: 1. Do one of the following: If it is the default WPS server that you are trying to restart, you can use the keyboard shortcut (this is Ctrl-Alt-S by default). From the main menu, select WPS Restart Server Local (or substitute the name of your remote WPS server in place of Local). Right-click on the required server in the Explorer, or Link Explorer, WPS Server Explorer, Results Output Explorer, and select Restart from the context menu. If Show advanced server actions is enabled in WPS Preferences for running programs preferences, then the single Restart menu option will not be available. Refer to Restarting with Advanced Server Actions below. 2. A confirmation window may be displayed, allowing you to cancel the restart if you wish. Click OK to clear everything - the log, all the output results, the Filerefs, libraries and datasets, and so on for that server. (You will not see the confirmation dialog if you have previously checked the Do not show this confirmation again option in the dialog.) 155

156 3. The datasets and Filerefs are removed from the WPS Server Explorer, the listing and HTML results are removed from the Output Explorer, and the associated log is cleared, and the links to the results are removed from the Results Explorer. Restarting with Advanced Server Actions This section is only relevant to users who have the Show advanced server actions option enabled in WPS Preferences. If this option is enabled, then, in the WPS server context menu in the WPS Server Explorer, Output Explorer, and Results Explorer, the following options are available for restarting the server, instead of the single Restart option: Restart, new WORK - Restart and clear all the contents of the Work library (as for a normal restart). Restart, keep WORK - Restart and keep all the contents of the Work library. 156

157 WPS Link client/server setup If you have configured one or more remote connections and servers, then you should be aware that there are 3 items required for a WPS Link client/server setup: an SSH (Secure Shell) server, the WPS software itself, and sufficient WPS licence keys to cover the setup. SSH server WPS Link requires the use of an SSH connection between the server and client machines. This is not supplied with the WPS software. However: For a UNIX (Linux, Solaris or AIX) server machine, the built-in SSH daemon can be used. For a Windows server machine, the third party SSH facility is available separately from Bitvise. Bitvise SSH is the only SSH facility officially supported by World Programming at present for a Windows server machine. WPS software WPS is supplied as a single installation file that contains all the WPS features required for use with WPS Link, including WPS Workbench, the Java Runtime Environment, and the licensable WPS server component. You will need WPS installation files that are suitable for the operating systems on both server and client machines. For example, if you have a Linux server machine and Windows client machines, you will need the Linux installation file for the server, and the appropriate Windows installation files (32-bit or 64bit) for the clients. Refer to the relevant platform installation guide for full details of the WPS installation process. WPS licence key(s) In order for a WPS installation to be able to execute a program written in the language of SAS, the WPS server component component needs to be activated by the application of a WPS licence key (supplied separately to the WPS software - refer to Applying a licence key). If you want to restrict the execution of programs to the linked server, then you only need a licence key for the server installation of WPS. If you want to be able to execute programs on either the client machine or the linked server, then you need separate licence keys for the server and the client installations of WPS. 157

158 Client/server installation summary A brief overview of the sequence of steps required to install and set up a WPS Link client/server solution is given below. Important: The person who installs WPS and applies the licence keys must have operating system administrator privileges on those machines. 1. Outside WPS, set up and test the SSH connection between the server and client machines in accordance with the platforms and authentication methods that are active at your site (refer to the WPS Link user guide and reference for details). 2. Install WPS fully on the server machine if you are going to be executing programs on that machine. When you launch WPS on the server, you will automatically be prompted to apply the licence. 3. If you have not already done so, install WPS on the individual client machine(s). When you launch WPS on the client(s), you will automatically be prompted to apply the workstation licence. If you are only going to be running programs on the linked server, and you do not therefore require a licensed installation of WPS on the client, then, provided that you are running Windows on the client, you can isolate the WPS Local Server from the installation (refer to Configuring the local WPS installation). 4. Inside WPS, create a link to the remote computer in the following two-step operation: a. Create a connection to the remote host (refer to Creating a new remote host connection). b. Add a WPS server to this remote host so that you can run your programs remotely (refer to Defining a new WPS server). Managing local and remote host connections This section covers the connection properties of both local and remote hosts, including the creation of directory shortcuts, and the import and export of connection definitions. Tip: You can also create directory shortcuts in the File Explorer, by right-clicking on the required folder, selecting New Directory Shortcut, and then supplying the required shortcut name in the Directory Name field of the Directory Shortcut dialog. 158

159 Local host connection properties (Directory Shortcuts) These properties are accessed by selecting the Local host connection in the Link Explorer, and then right-clicking and selecting Properties from the context menu. The only properties available for a Local host connection are Directory Shortcuts. A directory shortcut is a shortcut to a directory on the local file system. The local shortcuts that are created by default differ in accordance with the operating system on which you are running the Workbench: Windows users. There will be Home and Workspace shortcuts, and also a shortcut for each available local disk drive. For example, if you have drives 'C' and 'D' on your computer, there will be four shortcuts by default. Other operating systems. Only Home (~/) and Root (/) shortcuts are created by default. To set up a new shortcut, click Add to display the following dialog: After Directory Name, enter the shortcut name you want to use, and, after Directory Path, click Browse, select the required directory, and click OK. The shortcut name then appears in the host file system in File Explorer when the host connection is open. You can double-click a shortcut to change its definition. Other directory shortcuts can be edited as required, and removed from this property page. Creating a new remote host connection You will need to have access to a machine that has a licensed WPS server installation on a supported platform. You will also need to ensure that you have SSH access to the machine, and that you know the location of the WPS installation on that machine. You may need to contact the machine administrator to obtain this information, and to ensure that you have access. For details of the means of SSH authentication, refer to the WPS Link user guide and reference. Proceed as follows to create a new remote host connection: 1. Launch the New Remote Host Connection wizard by doing either of the following: 159

160 Ensure that you have the open, and click Link Explorer open ( Window Show View Link Explorer) New Remote Connection. From the main menu, select WPS Link New Remote Host Connection. 2. In the New Server Connection dialog, choose one of: New SSH Connection (3.1 Compatibility) New SSH Connection (3.2 and later -- UNIX, MacOSX, Windows) The first of the above options offers backwards compatibility, having identical behaviour to that present in WPS version 3.1. The second option includes support for establishing remote connections to Windows servers running Bitvise SSH Server. Regardless of whether or not you require Bitvise support, you should choose this option if there is no special reason not to. You should be aware that, if you select 3.2 and later, and then subsequently revert to WPS Version 3.1, you will lose any remote host connections that were set up in WPS Version Click Next and complete the following dialog: 160

161 For Hostname, enter the name or IP address of the remote machine to which you wish to connect. For Port, you can specify a port other than the default 22 if required, but, if so, you should verify it first with your system administrator. The Connection name defaults to the Hostname, but you can overwrite this to enter a descriptive name for the connection. Remember: Connection names must be unique, so, if you are creating multiple connections to the same host, you will need to modify the Connection name each time. For User name, enter your user ID on the remote host. In the last two check boxes, ensure that Open the connection now is ticked if the connection is to be opened now, and that Open the connection automatically on Workbench startup is ticked if the connection is to be opened automatically whenever WPS Workbench is started. Tip: If you are going to be using the connection regularly, select Open the connection automatically on Workbench startup so that, once the associated server starts, the connection is already open. 4. Press Next to define the connection's directory shortcuts: 161

162 A directory shortcut is a shortcut to a path on the host's file system. By default, there are directory shortcut defined for Home (~/) and Root (/). To set up a new shortcut, click Add to display the following dialog: After Directory Name, enter the shortcut name you want to use, and, after Directory Path, the full path (as shown when you hover over the location in File Explorer), and click OK. The shortcut name then appears in the host file system in File Explorer. You can double-click a shortcut to change its definition. 5. Click Finish. If you have not previously validated the authenticity of the remote host, an SSH2 Message dialog of the following kind shown is displayed: 162

163 If you are certain that the identity of the host is correct, click Yes. If you are setting this up in a production environment, you should explicitly confirm with a system administrator that the displayed RSA key fingerprint of the remote host matches that of the host to which you intend to connect. Once the host key has been confirmed, it is stored in WPS Workbench, and subsequent attempts to connect to the same host machine will not require this to be reconfirmed. 6. If you elected to open the connection immediately, you will now be prompted for a password to authenticate yourself on the host machine. Assuming that your system administrator has provided you with the required password, enter it in the Password Required dialog and click OK. There will now be an entry in the Link Explorer for your new connection. You will now need to add one or more WPS server definitions to this connection in order to use WPS (refer to Defining a new WPS server). Remote host connection properties Connection properties are accessed by selecting the required connection in the Link Explorer, and then right-clicking and selecting Properties from the context menu. The properties that can be selected via the left of the Properties dialog are as follows: Remote Connection Options This is where you set up the settings for a connection to a remote host. The Hostname, Port and User name entries allow you to specify the machine hostname or IP address of the remote server, the SSH port (defaults to 22 if not specified), and the user name you wish to connect to it with. 163

164 The Automatically open connection check box controls whether the connection is automatically opened when the Workbench is started up. The Enable Compression check box controls whether the ssh connection, and as a result the protocol traffic between the Workbench and the remote connection, is compressed or not. The Use SSH Port Forwarding check box controls whether or not the SSH connection uses SSH port forwarding to send standard in and out information between the remote connection and the Workbench. This requires your SSH daemon to be running with "AllowTcpForwarding yes" specified in the config file. If this is not enabled in your SSH daemon configuration, you should leave this unchecked or speak to your systems administrator to have it enabled. The Verify host name check box simply checks that the host you have specified in the Hostname entry exists. If you are in the process of setting up the remote host, or you know that it will exist at some point, then you can uncheck this box and the Workbench will allow you to save the settings. Otherwise, an error will be displayed and you will be required to specify a host that does cuurrently exist. Directory Shortcuts A directory shortcut is a shortcut to a directory on the remote file system. Default shortcuts are defined for Home (~/) and Root (/) (that it to say, the file system root directory). To set up a new shortcut, click Add to display the following dialog: After Directory Name, enter the shortcut name you want to use, and, after Directory Path, the full path (as shown when you hover over the location in the File Explorer), and click OK. The shortcut name then appears in the host file system in File Explorer when the host connection is open. You can double-click a shortcut to change its definition. Other directory shortcuts can be edited as required, and removed from this property page. Advanced connection options There are circumstances where it is necessary to control the list of environment variables that the remote server will inherit when it is started. By default the server process will just inherit the default interactive shell environment for the user under whose ID the server is being started. An example would be the environment variables required in order to use a database library engine. On Linux, for example, this might require that the database client shared libraries be added to the LD_LIBRARY_PATH so that they can be loaded by the WPS software. One way to do this is to modify the /etc/profile or ~/.profile file in order to add the required directories to the LD_LIBRARY_PATH. However this 164

165 may not always be desirable. An alternative on UNIX/Linux is to place a wpsenv.sh file in the WPS installation directory, or in your home directory. Its contents will be automatically run before the server is launched. The output from any commands that you execute in this way can be seen in the Console view (refer to Console (for remote server standard output)). On Windows, if you want the WPS server to acquire any special environment variables, you will need to configure them in the normal way - by using the Control Panel to set them either as system environment variables or specific to the relevant user. Caution: All processes running as that user will see those variables, and there is no way to specify that they should only be visible to the WPS process. Defining a new WPS server WPS Workbench allows you to have multiple WPS servers defined on a particular host connection. Proceed as follows to define a new server: 1. Having ensured that your connection to the host is open, launch the New WPS Server wizard by doing one of the following: Ensure that you have the open, right-click on the Link Explorer open ( Window Show View Link Explorer) host connection to which you wish to add a server, and click on the New WPS Server option in the context menu. From the main menu, select WPS Link New WPS Server Local (or substitute the name of your remote WPS server in place of Local ). 2. In the resulting New WPS Server dialog, enter the Server name (this must be unique across all connections). If you are defining a New Remote WPS Server, there will be a field called Base WPS install directory, and in here you need specify the location of the WPS installation on the remote host, for example: 165

166 3. In the last two check boxes, ensure that Start the server now is ticked if the server is to be started immediately, and that Start the server automatically on connection startup is ticked if the server is to be started each time the connection is opened. 4. Click Finish to complete the wizard and create the new server definition. There will now be entries in the Link Explorer, WPS Server Explorer, Output Explorer and Results Explorer for your new WPS server definition. Follow the steps in Local WPS server properties or Remote WPS server properties as appropriate, to configure startup options for the server. Exporting host connection definitions to a file To simplify sharing host connection definitions within a work group, or to enable you to copy connection definitions between workspaces, you can export connection definitions to a file, as follows: 1. Ensure that you have the Link Explorer open ( Window Show View Link Explorer). 2. Select the connections that you wish to export from the list in the Link Explorer view. 3. From the right-click menu, select Export Host Connection. 4. Using the resultant Export to File dialog, enter the name of the file that you wish to create. This file will contain the exported connection definitions in XML form, and have the extension.cdx. The host connection definitions will be saved to the selected file. This file can then be distributed within your work group, or imported directly into another workspace on your machine. To import the connection definitions into a workspace, refer to Importing host connection definitions from a file. 166