WPS Workbench. user guide. "To help guide you through using the WPS user interface (Workbench) to create, edit and run programs"

Transcription

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

2 Contents Introduction...6 About This Guide...6 About WPS... 6 Users of SAS Software... 7 Getting Started... 9 Workbench Basics... 9 WPS Components Cheat Sheets Concepts Eclipse...17 Workbench Perspectives...17 WPS Perspective View Stack Views...20 Help View...20 Project Explorer View Link Explorer View...21 Properties View...23 Outline View...23 Output Explorer View...24 Results Explorer View...25 File Explorer View...26 WPS Server Explorer View Editor and Output View Progress View...30 Bookmarks View Tasks View Search View...32 Console View Projects Project Definition File...33 Working with Multiple Projects...34 WPS Link Host Connection...34 WPS Server Workspace Programs...36 Program Names

3 Working with Multiple Programs...37 Program Colours and Layout Program Writing and Editing Local History Running a Program Managing ODS Output Analyser Tools...41 Analysis Reports Markers Bookmarks...42 Tasks Context-Sensitive Help Dialogs File System Operation Tasks...45 Working with Workbench Views Opening a View Closing a View...45 Resizing a View Moving a View Using a Detached View Minimise a Window...47 Maximise a Window...47 Restore a Window Working with Perspectives Resetting a Perspective...48 Saving a Perspective...48 Deleting a Perspective...48 Opening a Perspective Closing a Perspective...49 Switching Between Open Perspectives...49 Work the Way You Want Working with Projects Creating a New Project Copying a Project Deleting a Project Closing and Opening a Project Exporting A Project...51 Importing Files or Archive Files...51 Importing an Existing Project...52 Switching to a Different Workspace Migrating Existing Programs or Projects...53 Migrating from Previous Versions of WPS Migrating from SAS Software...53 Working with Files And Folders

4 Project Explorer File Management File Explorer File Management Working with Editors...61 Opening editors with Project Explorer...61 Opening Editors with File Explorer...62 Working with Programs Creating a New Program...63 Opening a Non-Project Program Opening a Project Program...64 Getting Help While Writing Programs...64 Running Programs Restart Server...70 Linking the Active Program with the Project Explorer view...71 Working with WPS Links Creating a New Remote Host Connection Creating a New Local WPS Server...73 Creating a New Remote WPS Server...74 Exporting Host Connection Definitions to a File...75 Exporting WPS Server Definitions to a File Importing Host Connection Definitions from a File...76 Importing WPS Server Definitions from a File Selecting the Default Server Connection Working with Program Output Working with Logs Working with Listing Output...79 Working with HTML Output Clearing the Results Output Working with Data Sets Analysing Programs and Language Elements...82 Analysis Restrictions...82 Analyse Mainframe Programs Analyse Program Compatibility...83 Analyse Language Usage...83 Opening Analysis Reports Navigating Analysis Reports...84 Export Analysis Results to Excel...85 Working with Markers Working with Bookmarks Working with Tasks...86 Working with Local History...87 Compare with Local History Replace with Local History Restore from Local History...88 Local History Size and Duration...88 WPS Tips and Tricks

5 Reference License Key Applying a License Key...90 Viewing Your Applied License Details Preferences...90 Preference Filter...91 General...91 General Local History General Text Editors General Text File Encoding WPS WPS Code Injection...94 WPS Code Templates...94 WPS Data Set Viewer WPS File Explorer WPS Result Options...95 WPS Syntax Coloring WPS Log Syntax Coloring...95 Backing Up Your Preferences Editing and Navigating...96 Undo and Redo Your Edits...96 Find...96 Navigate Back and Forward Go To Your Last Edit Next and Previous Annotation...97 Host Connection Properties...97 Local Host Connection Properties...98 Remote Host Connection Properties...98 WPS Server Properties Local WPS Server Properties...99 Remote WPS Server Properties WPS Server LOCALE Setting WPS WORK Location Using ODBC Command Line WPS Configuration Files AutoExec files Welcome Pages Legal Notices Reporting problems

6 Introduction About This Guide Overview This user guide is intended to help you get started with the World Programming System (WPS). It is designed to guide new users through the user interface of WPS, with which you can create, edit and run programs written in the language of SAS. This user guide is not designed to train you in the use of the language of SAS. If you are not familiar with the language of SAS there is a wide range of educational and reference material available from many sources. It is not the intention of this guide to teach you every option within WPS. Once you have worked through this guide you should be sufficiently familiar with the system to write your own programs and to begin processing and analysing data. Notation Whenever you need to type in code the guide will show it like this: /* Hi - here is some code */ PROC OPTIONS; RUN; In general this guide will use menu options when suggesting you need to interact with WPS, but there are also toolbar buttons and context-menu options for many of these options. Menu and button options will be shown with a font like this. An example of a menu item could be File > New > Project. This means you should click on the menu option 'File', then the option 'New' and then 'Project'. About WPS Overview The World Programming System (WPS) fundamentally consists of two components: a Graphical User Interface (GUI)/Integrated Development Environment (IDE) known as WPS Workbench. 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 (known as WPS Server) and is used to process and execute programs. 6

7 WPS Server WPS Server provides the ability to read and run programs. WPS Server cannot be launched directly; it is launched by WPS Workbench during operation. WPS Workbench The GUI/IDE, known as the Workbench, provides facilities to manage, create and edit programs and then to run programs with the WPS Server. The Workbench uses Eclipse, originally written by IBM and now part of an open source project, as the framework for the GUI. WPS Workbench is an extension of Eclipse specially designed to allow users to edit and run programs written in the language of SAS. It is worth noting that 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 wealth of other uses. 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. WPS and SAS Software WPS supports programming language elements from the language of SAS. This means that programs developed in a SAS software environment may be run, edited, shared and saved in WPS and vice versa. Besides a familiar programming language, WPS provides a wealth of other features for Users of SAS Software already familiar with using products from the SAS Institute Inc. Users of SAS Software Overview If you are accustomed to using other products related to the language of SAS such as software produced by SAS Institute Inc, you will find that the language support in WPS is familiar. You can expect to find many of the same syntax and options for procedures, formats, macros, DATA Steps, etc. WPS will also provide other recognisable features and objects such as logs, data sets, WORK library, etc. Other features may be new to you, such as the Workbench environment itself and the way 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 read programs written in the language of SAS, WPS is also able to read and write from and to data files used by SAS software. WPS has a wide selection of library engines to allow you to connect to many leading third-party databases. 7

8 WPS also uses a proprietary data file format known as WPD. As the default data set library engine, WPD datasets are used for the WORK library. Because it is the native data set library engine to WPS, it has the most complete feature support. For example the WPD engine supports indices. Supported Language Elements WPS does not support every element in the language of SAS. The Workbench has Analyser Tools to help determine if any existing language of SAS programs you have contain unknown or unsupported language elements. Please refer to the help guide entitled WPS Reference for Language Elements for details on the syntax of the language elements that are supported by this release of WPS. Existing Programs in the Language of SAS WPS uses the name program to refer to a program written in the language of SAS. To use existing programs within WPS Workbench, you should refer to the Migrating from SAS Software section in this guide. 8

9 Getting Started Workbench Basics Overview The term Workbench is used to describe the whole desktop development environment. The layout of the Workbench can be changed to suit your preference. These layouts are called Perspectives and they contain different views, editors and control what appears in the menus and tool bars. A perspective can be changed by, for example, moving or removing views, resizing views and so on. The default WPS perspective is depicted in the figure below: WPS uses the concept of Projects to hold the files and folders that relate to each other. For example, you might have a project containing programs still under development, another project for monthly reporting applications, and so on. Projects are folders that are themselves held in a parent folder that is referred to as the Workspace. If you would prefer to simply access the file-system directly to manage programs (rather than using Projects), this is possible via the File Explorer View. 9

10 Views Displayed in the WPS Perspective Project Explorer : Displays in a tree structure all the projects in your workspace. It allows you to open files for editing and manages the programs and other files contained in a project. More about the Project Explorer View File Explorer: Displays local and remote Host Connection file systems in a tree structure. You may use this instead of the Project Explorer to manage files if you wish. More about the File Explorer View Editor and Output: Displays the contents of a program and allows you to edit it. It can also display the output generated by a program such as data sets, logs, HTML, etc. More about the Editor and Output View Outline : Displays either the structure of a program (e.g. globals, data steps, procedures and macros) or log (e.g. errors, warnings) that you have open in the Editor and Output view. More about the Outline View Properties : Displays the details of objects like project folders, programs, libraries, data sets, variables, etc. More about the Properties View Output Explorer : Displays in a tree structure the output (logs, HTML output, listing output) generated from running a program. It also allows you to open the output into the Editor and Output view. More about the Output Explorer View Results Explorer : Displays in a tree structure links to every ODS item generated to the various destinations (e.g. HTML or listing) from running a program. Each individual element can be clicked on to see that particular output in the associated Output view. More about the Results Explorer View WPS Server Explorer : Displays in a tree structure the servers, libraries and their contents (e.g. data sets, libnames, etc) that have been used by a program that has been run. More about the WPS Server Explorer View Link Explorer: Displays in a tree structure the Host Connections and local and remote WPS Servers. More about the Link Explorer View Progress: Displays the name of the program that is currently being executed or the names of programs that are queued up, waiting to run. You can also use this view to stop a program running or to remove queued up programs. More about the Progress View Console: Displays any output produced on standard output or standard error by a remote WPS Server locally in the Workbench. More about the Console View Help: This view is not open by default. If you need help on any particular item in the user interface, context sensitive help is usually available by pressing F1, or by using the Help > Dynamic Help menu option. Note that once you have navigated away from the dynamic help page (identified by the title Related Topics), the help view will no longer dynamically update as you move around the user interface. However you can always get context sensitive help on the current item by pressing F1, or by using the Related Topics link at the top of the Help view. More about the Help View. 10

11 WPS Link: WPS Link is the collective term for the technology used to provide a client/server facility. It comprises of Host Connections and WPS Servers. More about WPS Link. WPS Components Objects Managed by the Workbench Projects: These are the fundamental unit of organisation for resources you wish to use in the Workbench. Typically you would 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 edit programs using the WPS program editor. This editor uses colour coding to highlight different language elements as well as syntax errors. WPS recognises a program as a file with either the extension.sas or.wps. Log: 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 WPS 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. Managed 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 have the Workbench manage the process automatically. The default option is for the Workbench to produce managed HTML output. Libraries: These hold the temporary files, data sets, catalogs, etc that are created as a result of running a program. Data Sets: The data generated from running a program is stored in data sets. You can view the contents and properties of a data set through various views within the Workbench. Host Connection: A Host Connection defines a computer, local or remote, that Workbench has access to. WPS Server: The WPS Server is the engine responsible for executing programs and generating the resulting output, such as the log, listing output, HTML result files and data sets. A WPS Server is 11

12 associated with one Host Connection. The WPS Server also maintains an environment of assigned libraries and filerefs, defined macros and macro variables and so on with which all of the running programs interact. Shortcut Directory: A Shortcut Directory defines a directory on a computer file system (local or remote), and is available in the File Explorer View for easy access to that directory and others below it. Cheat Sheets About The Workbench is supplied with tutorials that are known as 'cheat sheets'. They are designed to help you get started with using WPS by introducing you to certain tasks and features. A cheat sheet is laid out as a sequence of steps that you 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 Sheets Types Cheat sheets can be one of two different types, simple, or composite. A 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 follow, as 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 lots of tasks, into smaller manageable groups. Each of these groups has its own introduction and conclusion as below: 12

13 Composite cheat sheets have two panes in the user interface. One shows the groups of tasks, while the other allows you to work through the tasks in each group. 13

14 Normally 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's main menu. Launching a Cheat Sheet from the Welcome Pages: 1. Open the Welcome page by selecting the menu item Help > Welcome. 2. Select the Tutorials page. 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 (not from the Welcome pages), you will get a quick toolbar of buttons specifically for use with the cheat sheet. If you launch a cheat sheet from the Welcome page, you will not get this toolbar. The buttons available in the cheat sheet quick toolbar and tab are listed below: 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 you already have a cheat sheet active, its completion status is automatically saved and then the new selected cheat sheet is opened. Only one cheat sheet may be open at a 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. Starting the Cheat Sheet Each cheat sheet has a sequence of steps that always begins with an Introduction step. When you launch a fresh cheat sheet, the Introduction step is expanded so that you can read a brief description about the selected cheat sheet. For simple cheat sheets, to start working with the cheat sheet, select Click to Begin at the bottom of the Introduction step. The next step is expanded and highlighted. You should also see action buttons at the bottom of the next step, such as in the cheat sheet. Click to Complete. You can now progress through each step For composite cheat sheets, after reading the introduction you can start the first sheet by clicking the Goto to link at the bottom. You will then get the introduction for the first group of tasks, and you may 14

15 then click on the as a simple cheat sheet. Progressing Through the Steps Start working link to begin. From this point on, the task group behaves very much 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. Composite cheat sheets behave in much the same way, until you complete all the sheets in the group you are on. 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 put you in the introduction for the next group. Getting Related Help Information To get detailed instructions or related information for a particular step, select the icon in the upper right of that step. The related help will open in a separate Help window. Open Any Step You can open any step out of sequence whether it is its expand Open Related Help marked as completed or not by simply selecting icon. Any step opened in this way will not change from its completed or uncompleted state. Also notice that steps after the active step do not have a Click to Complete icon. Click on the Collapse All Items but Current button 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 the 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 (e.g. programs, projects, etc) 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 the 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. Composite cheat sheets are considered complete when all task groups are 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. 15

16 Closing the 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. 16

17 Concepts Eclipse WPS utilises the Eclipse platform as the basic framework for providing the Workbench user interface. 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, etc. WPS Workbench is an example of the Eclipse environment supplied with a suite of plug-ins suitable for editing programs written in the language of SAS and running them with the WPS Server (see WPS Server). 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 Eclipse-based plug-ins and extensions. For more information about Eclipse and other available plug-ins, please visit the web site at Eclipse Features Not Used by WPS Under the Project menu, none of the Build or Clean menu items are used by WPS. The Help > Software Updates menu item will not retrieve updates for the WPS software. These menu items will only retrieve updates to the Eclipse platform itself or other new or updated third-party plug-ins. Workbench The term Workbench refers to the Integrated Development Environment (IDE). This environment utilises the Eclipse platform as the basic framework to provide the Graphical User Interface (GUI). IDE and GUI can be used interchangeably. The customisable layouts that can be utilised in the Workbench are known as Perspectives. As well as the visible objects that the Workbench manages such as Views and the WPS Components, there are other features that the Workbench handles such as the Local History and WPS Servers. Perspectives The position of available views, windows, view stacks, menu items, and toolbar buttons displayed and the general layout of the WPS Workbench is known as a perspective. A perspective can be customised to look the way you want by moving, resizing, adding or removing different windows and views. The Workbench allows you to save customised perspectives and to switch 17

18 between different perspectives. Refer to the Working with Perspectives section in this guide for more details about changing the layout of the Workbench. All available perspectives, including any customised perspectives you save, can be opened from the Window > Open Perspective menu. WPS Workbench is supplied with several different perspectives. Only the WPS perspective is described in this section of the guide because it is the only one designed specifically for use with programs. WPS Perspective A Programs. WPS perspective is specifically intended for the task of creating, managing, editing and running This perspective is the default used when you first install WPS Workbench. Its layout is depicted in the figure below. You cannot delete or rename the WPS perspective. However, you can save your own screen layout under the same name, thus replacing the original layout. Noteworthy Features By default, this perspective has the following features specifically for tasks concerned with managing or using programs: 18

19 Extra toolbar buttons concerned with running programs. The WPS main menu item. Views for locating and opening program output files. To Display this Perspective Select the menu item Window > Open Perspective > Other... > WPS. View Stack Views are organised in Perspectives by being members of a view stack. A view stack is a collection of views that are all allocated the same area in a perspective. For example, the view stack below contains 2 views: When opening a view, it is opened in the view stack of which it was last a member. This is recorded in the perspective for each view. For example, opening the Progress View will add the view to our example view stack. View stacks are an important concept to understand when it comes to moving, minimizing, maximising and restoring views. 19

20 Views The layout of the items with the WPS Workbench application is known as Perspectives and comprises individual windows that contain one or more views. These views display specific types of information and provide specific functions. Many views also have specific toolbars located in the top right of each view. In the Working with Workbench Views section of this guide you can find out how to add, remove, resize or dock individual views in any position on the Workbench. Help View As you select different views of the Workbench you can automatically display relevant help items in the context-sensitive Help view. To Display this View To add this view to the current perspective, select the menu item Window > Show View > Other > Help > Help. Alternatively, you can press F1 on your keyboard to open this view. Help View Controls As you navigate about by clicking on the various links and buttons in this Help view, you will see numerous different controls available: Related Topics: If you follow any of the links in the Help view while it is docked inside the Workbench, ensure you click on the Related Topics link (at the bottom of the Help view) to jump back to the actual context-sensitive page. Otherwise the Help view will not automatically update as you continue to use the Workbench. Show in External Window: This will open a Help window outside of the Workbench with a contents tree view of all available topics. this external view is not context-sensitive. Show in All Topics: This will synchronise the help topic you are looking at with its position in the contents tree view of all available help topics. 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 Search:Use this facility to search help for specific keywords. Bookmarks link in the Help view. Project Explorer View The files and folders that can be edited and managed by the Workbench can be displayed in a tree structure in the Project Explorer view. To Display this View To add this view to the current perspective, select the menu item Window > Show View > Other > General > Project Explorer. The Files and Folders Displayed The main file and folder objects that the ProjectsExplorer displays are: 20

21 Open projects Closed projects Folders Programs (i.e. any file with the extension.sas or.wps) Other Files (text or unknown file extensions) Any type of file can be put in a project and listed by the Project Explorer. If your computer system recognises the file type, then the appropriate icon is displayed (e.g. a DOS batch file). Note: The Project Explorer only displays projects that are in your current Workspace. Working with Projects The items in a Project represent objects within the filesystem under the project home directory. For more information about the Workbench tools available for manipulating projects please refer to the Working with Projects section in this guide. Working with Files and Folders For more information about the Workbench tools available for manipulating the various objects displayed in a project, please refer to the Project Explorer File Management section in this guide. Alternatives File system objects can also be managed using the And Folders for help on choosing which view to use. File Explorer View. Refer to Working with Files Operating System Tools As well as the Workbench's tools, you can use your operating system facilities to delete, cut, copy and paste objects into a project. You may need to use the Workbench's refresh tool to refresh the Project Explorer to ensure that objects manipulated in this way are displayed (right mouse click on the and from the popup menu, select Refresh). project Note: If you do use the operating system tools instead of the Workbench tools, you will NOT have the added benefits that Local History provides. Link Explorer View The Link Explorer allows you to manage Host Connections you have configured, and also any WPS Servers on these connections. To Display this View To add this view to the current perspective, select the menu item Window > Show View > Other > WPS > Link Explorer. Objects Displayed There are only two node types visible in this view: 21

22 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. Properties With the exception of a local Host Connection, if you select any other item in the Link Explorer view, you will see information about that item displayed in the Properties View. You can also get more detailed properties about certain items in the Link Explorer view. Right mouse click on an item and from the popup menu, select the Properties option if it is enabled (i.e. there are properties available for the selected item). Below are the items that this option works with, and the sort of information you can expect to see. Host Connection Properties Remote Connection Options: Hostname, credentials and startup options for the connection. Shortcut Directories: A shortcut directory is a shortcut to a path on a file system. WPS Server Properties Environment: Details of the server's environment (working directory, process id & environment variables). Launch Options: Local servers only. License Information: Full details about your license key. Macro Variables: The list of all automatic and global macro variables used by the server. Software: Information about the WPS software such as the version number. Startup Options: Auto-start, installation directory (for remote servers), initial directory and startup system options. System Options: The currently applied system options. For more information about this topic, please refer to the Configuration Files section in this guide. Commands Collapse All Collapse the Connection Tree down to show the primary Host Connection nodes. New Remote Connection Add a new remote connection. Only one local connection can exist. Import Connection Import a connection definition file. Drag and Drop 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 whilst dragging will copy the WPS Server. To maintain unique names, the copied server will be renamed automatically. The server can be renamed manually by right-clicking the server and selecting Rename from the context menu. 22

23 Host connections can be imported by dragging Connection Definition Files (*.cdx) onto the Link Explorer view. For further information on importing connections, see Importing Host Connection Definitions from a File. Servers can be imported by dragging Server Definition Files (*.sdx) onto a Host Connection node in the Link Explorer View. For further information on importing servers, see Importing WPS Server Definitions from a File. Properties View 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 the menu item Window > Show View > Other > General > 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 View WPS Server Explorer View Search View File Explorer View Link Explorer View Note: Not all objects in the views listed above have viewable properties. The WPS Server properties include the following information about a License: Expiry Date Grace Period Licensed Operating System License Number Outline View To assist in navigating programs, logs, listing or HTML output the Workbench displays structural elements contained in these files in the line in the file will be highlighted. Outline view. If you click on a structural element in this view, the relevant Opening or giving focus to a program, log, listing or HTML result file will make the Outline view automatically refresh to display the structural elements that are relevant to the file that has focus. 23

24 To Display this View To add this view to the current perspective, select the menu item Window > Show View > Other > General > Outline. Program Structural Elements Opening Programs will make the Outline view display these structural elements: Global Statement DATA Step Procedure Macro You can control which structural elements are displayed in the program's Outline view. In the quick tool bar at the top of this view you will see icons with a diagonal line through them representing structural elements. These buttons will toggle off and on the relevant structural element in the Outline view. Log Structural Elements Viewing the Log will make the Outline view display these structural elements: An individual log entry and the parent node for errors and warnings Error Warning Listing and HTML Structural Elements Viewing the Listing Output or Viewing HTML Output, will make the Outline view display these structural elements: Results parent node HTML tabular output Listing Tabular output Output Explorer View The output files generated from running a program, are listed by, and can be opened from, the Explorer view. Output Note: To view hierarchical lists of results, grouped by server, please use the Results Explorer View. While the Workbench is open, the output from previous runs is not automatically deleted. In order to clear previous output, you can use the WPS > Clear Log or WPS > Clear Results or the relevant toolbar buttons or context menus. Alternatively you can use the Restart Server feature. 24

25 To Display this View To add this view to the current perspective, select the menu item Window > Show View > Other > WPS > Output Explorer. Output Output items are associated with, and listed underneath the server on which they were generated. The following output items is always shown under each server whether any programs have been run yet or not: Log output The following output items may be shown under a server if that server has run programs that have generated output of one or more of the following types: Listing output HTML output Once you run a program that generates output of one of the above types, you will see the related output nodes appear below the WPS Server they were generated by. There will only ever be at most one node shown for each type of output under each registered WPS Server. This represents all the cumulative output of that type generated by that particular server. Double clicking on one of the output nodes will open the associated output of that type for that WPS Server in its relevant editor. If the output type is anything other than log output then at the same time as the output is opened in the editor, you will also see the individual result elements listed in the Results Explorer View which you can use to navigate the output. Working With Program Output For details about listing, opening, printing or saving the logs or results output please refer to Working with Program Output. Results Explorer View This view contains hierarchical links to all the results from every program that has been executed, grouped by server, since the last time that server was started or restarted Note: To view all output, including the log, please use the Output Explorer View. To Display this View To add this view to the current perspective, select the menu item Window > Show View > Other > WPS > Results Explorer. Output Once a program is run an entry will appear 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 specified. Output types can be: 25

26 WPS managed HTML output WPS managed Listing output Manually managed HTML output Manually managed Listing output For more information about what WPS managed and manually managed results means please see: Managing ODS Output To change which outputs are produced by default please see: WPS Result Options Working With Program Output For details about listing and opening data sets, please refer to Working with Program Output. File Explorer View The files and folders that can be edited and managed by the Workbench are displayed in a tree structure in the File Explorer view. To Display this View To add this view to the current perspective, select the menu item Window > Show View > Other > General > File Explorer. File Explorer Objects The main file and folder objects that the File Explorer displays are: Connections: The root node that represents a connection to a host machine. Can be either local or remote. Shortcuts: A directory on a filesystem selected for management in the File Explorer. Directory: A child directory of a Shortcut or another child directory. 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 file system via a symbolic link. Symbolic linked directory: A file that points to another directory in the host file system via a 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. Note: The File Explorer only displays connections that are open. 26

27 Working with Connections and Shortcuts It is only possible to view files on remote systems when you have an open Host Connection. Host Connections can be opened from Link Explorer View, and connections are also opened when starting WPS Servers in the WPS Server Explorer View. Each Host Connection is configured to have one or more Shortcut Directories, that permit access to the files and folders on the file system. When a Host Connection is opened, then the a connection will remove it's node from the File Explorer View. Connection will appear in the File Explorer View. Closing Host Connections expand into Shortcut Directories in the File Explorer View. Shortcut Directories that are invalid are shown with an Invalid Shortcut icon. This means that the path configured for these shortcuts is not available on the file system for that connection. Properties Selecting items in the File Explorer View will reveal information about that item displayed in the Properties View. Note that the properties differ when using local or remote Connections. Connection Properties Remote Connection Options: Hostname, credentials and startup options for the connection. Shortcut Directories: A Shortcut Directory is a shortcut to a path on a file system. Local Shortcut Directory, File and Folder Properties Modified date & time. Is Link, which is 'Yes' if the currently selected item is a symbolic link. Name of the item. Size of files (directory sizes are not shown) Link details (if the item is a symbolic link, such as the link path). Additionally, on a remote system, the following properties are also available. Remote Shortcut Directory, File and Folder Properties Accessed date and time. Group and user id's. 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 Shortcut Directory, 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. 27

28 Run On: Run any selected programs on a WPS Server. Refresh: Refresh the currently selected node in the File Explorer from the file system. Rename: Rename the currently selected file or directory. Analyse: Analyse the contents of programs and folders containing programs (see Analysis Reports). These options are available from the context menu within the File Explorer, and also from the main menu. For more information about performing operations, see File Explorer File Management. Progress Progress of the current operation can be seen in the Progress view. For more details on working with the Progress view, please use the following sections of this guide: Progress View Running Programs Programs can be run by selecting a program (or a number of programs), right-clicking and moving the mouse cursor to the Run On menu option in the context menu. The menu will then expand to show the list of servers the program can be run on. Choosing a server will then run the program on that server. For more information on running programs please see the following sections of this guide: Running a Program Alternatives File system objects can also be managed using the And Folders for help on choosing which view to use. Project Explorer View. Refer to Working with Files WPS Server Explorer View All file references, libraries, catalogs and data sets that have been generated as a result of running a program are listed by, and can be opened from, the WPS Server Explorer view. While the Workbench is open, the file references and library contents from previous runs are preserved. In order to clear the state of a server, you need to use the Restart Server feature. To Display this View To add this view to the current perspective, select the menu item Window > Show View > Other > WPS > WPS Server Explorer. Objects Displayed Assuming you have run a program, you should see a simple hierarchy displayed: WPS Server node: The root node that represents the WPS installation where you are running your programs. This is probably a Local installation of WPS. Libraries: A parent node for individual library items. 28

29 Library: A collection of catalogs and/or data sets. Catalog: A collection of user defined items such as formats and informats. Data Set: A data file containing numeric and/or character fields. Data Set View: A data set that is created by executing a view in the source data. Numeric Data Set Field: A data set field that contains numeric values. Character Data Set Field: A data set field that contains character values. FileRefs: The parent node for fileref items. FileRef: An individual reference to a file. You may 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 listed in the WPS Server Explorer view. Working With Program Output For details about listing and opening data sets, please refer to Working with Program Output. Properties With the exception of the Libraries and FileRefs nodes, if you select any other item in the WPS Server Explorer view, you will see information about that item displayed in the Properties View. You can also get more detailed properties about certain items in the WPS Server Explorer view. Right mouse click on an item and from the popup menu, select the Properties option if it is enabled (i.e. there are properties available for the selected item). Below are the items that this option works with and the sort of information you can expect to see. Server Properties Software: Information about the WPS software such as the version number. License: Full details about your license key. System Options: The currently applied system options. For more information about this topic, please refer to the Configuration Files section in this guide. Library Properties General: The Name, Engine and Physical Location values together with Readonly and Temporary flags. Members: A table of information about the members of the catalog showing the member name and member type. Catalog Properties Entries: A table of information about the entries in the catalog showing the entry name, entry type and description. General: Name of the catalog. Catalog Entry Properties General: Name, type, description, creation and modification time of the entry. 29

30 Data Set and Data Set View Properties General: The field count and number of observations. Columns: A table of information about the data set fields including name, type, length, label, format and informat. Editor and Output View When you open any type of file in the Workbench e.g. programs, logs, output, data sets, text files, etc, they are opened as tabs in the Editor view. The Editor is always open and cannot be closed. However, you can close individual files that are open in the Editor. Because the editor cannot be closed and is always available, the Editor view is not listed under the Window > Show View menu. It is possible to split the Editor view so that you can view and/or modify two or more files at once. This is useful for comparing contents of two files for example. Once a file has been opened in the Editor you may or may not be allowed to edit (make changes to) it depending on the type of file it is, and how or from where it was opened. You cannot edit logs and output files opened from the Output Explorer View. You cannot edit a data set opened from the WPS Server Explorer View. Files opened from the Project Explorer View can normally be edited. You can even select which editor to use when opening the file as discussed in the Working with Editors section of this guide. You can also open files for editing from the File Explorer View. Some file types will open inside the workbench and will be opened in the Editor view. Progress View When you are Running a Program, it is listed as executing in the Progress view. Also, operations performed in the File Explorer View are also visible here (both operations that are in progress, and those that are complete). While a program is executing, and during File 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 you have the Progress View open or not. To Display this View To add this view to the current perspective, select the menu item Window > Show View > Other > General > Progress. File Explorer Operations An operation performed from the File Explorer View will remain in the progress view until another operation is performed. This allows you to see the results of the operation, if desired. An example of a successful operation is below: 30

31 An unsuccessful operation will appear as follows: Clicking on the link will reveal the File System Operation Dialog, showing you more detailed information about the operation. Working with the Progress View For more details about working with the program's Progress View, please refer to the following sections in this guide: Stopping a Run File System Operation Bookmarks View 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 View. To list and navigate between your bookmarks, you need to use the Bookmarks view. Note: This view will list all bookmarks regardless of whether the programs are open or not. However, it will not list bookmarks from programs in a closed project. 31

32 Note: It is not possible to create bookmarks on files opened from the File Explorer View, unless they are members of a project. This is because files opened outside of Projects may be anywhere in the filesystem, 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 the menu item Window > Show View > Other > General > Bookmarks. Tasks View You can add Tasks (reminders) against any line in a program that has been opened from the Project Explorer View, and associate 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. Note: The Tasks view will list tasks regardless of whether the programs are open or not. It will not list those from programs in a closed project. Note: It is not possible to create tasks on programs opened from the File Explorer View, unless they are members of a project. This is because programs opened this way may be anywhere in the filesystem 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 the menu item Window > Show View > Other > General > Tasks. Search View The results of performing a search are displayed in the the file right where the item appears. Search view. You can use this view to open To Display this View To add this view to the current perspective, select the menu item Window > Show View > Other > General > Search. Types of Search The main menu option Search > Search is a flexible tool that provides a wide variety of functionality: Search for a text string contained in any file in any open project in the Workbench. You can use wild cards in the search pattern. Search for files of a certain pattern contained in any open project in the Workbench. Search and replace text contained in any file in any open project in the Workbench. Note: The Search view opens automatically to display the results of a search. 32

33 Console View The Console view is not currently used if you are only running programs on a local server. In this situation it will remain blank. 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 remote WPS Server will be echoed into 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 will be displayed in the Console view. It is also extremely valuable when a remote server fails to start, or terminates abnormally. In this situation error text is typically displayed in the Console view. To Display this View To add this view to the current perspective, select the menu item Window > Show View > Other > General > Console. Projects As far as the Workbench is concerned, a project is a parent folder that contains other objects such as Programs, files, folders, etc. This parent or project folder is defined by a project definition file called.project. The items in a Project represent objects within the filesystem under the project home directory. There is no limit to the number of projects you can have open within WPS Workbench or to the number of folders and files a project may contain. Files may also be of any type. More information about using files, folders, projects, etc can be found in the Working with Projects section of this guide. All projects belong in a Workspace. You can only work with one workspace at a time within the Workbench but you can switch between different ones as desired. The Project Explorer View is used to display and manage the current workspace and the projects it contains. Project Definition File In the root directory of a project is a project definition file called.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 View. If you look at the project folder outside of the WPS Workbench, you will see this file. Caution: Do not move this file from the root directory of the project folder Do not delete or edit this file Do not copy, move or import this file into another project folder 33

34 Working with Multiple Projects More than one project can be open at any one time in the Workbench. There are many ways to end up with multiple projects in the Workbench: Creating a New Project Importing an Existing Project Copying a Project Note: You can move, copy, cut and paste items between projects. For more information about using these facilities in the Workbench, please refer to the Working with Files And Folders section in this guide. WPS Link WPS Link is the collective term for the technology used to provide a client/server facility. Using the WPS Workbench GUI on your local PC (the client) you can connect to a networked computer (the server) to manage and run programs on that remote server. WPS Link involves using concepts we refer to as Host Connection and WPS Server. Host Connection Host connections allow users to access computers, either for running programs (via a WPS Server) or for managing files and folders. Local Host Connections are available if the local WPS Server component is installed. This allows you to have one or more local servers for running programs written in the language of SAS. The ability to have multiple WPS Server nodes can be a useful way to setup different options or locale settings to use when running your programs. Remote Host Connections allow you to connect to remote computers. They have additional properties that must be configured when they are created, so that the Workbench can communicate with them. WPS Servers can only be added to Host Connections. A program can only be run on a WPS Server and cannot be run on a Host Connection alone. Management of files and folders on remote systems is possible via the File Explorer View. WPS Server In order to run a program (see Running a Program), the Workbench requires a connection to a WPS Server. The term Server here is used to refer to a server process. The process may be running on the local workstation machine (a local Host Connection), or may be running on an installation of WPS on a remote machine (a remote Host Connection). 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. Further 34

35 local servers can be created if required (see Creating a New Local WPS Server) or the local server can be deleted. 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. The term Remote Server refers to a WPS Server running under a Host Connection on a remote machine. Such a set up will require a licensed WPS Server installation on the remote machine. Setting up remote server connections gives the user the ease of use of the Workbench at their local workstation while giving them access to the processing power of a remote server machine. Multiple servers can run under a single remote Host Connection. Once a connection to a remote machine is 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. Remote connections can be created by following the steps in Creating a New Remote WPS Server The list of servers that are defined is stored within the Workspace, so changing your workspace will load a new list of servers, which may differ. It is not possible to edit this list directly, but it can be maintained with the Link Explorer View. For 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). The WPS Server Explorer View and Link Explorer View will show the list of servers (Server Explorer) or connections and servers (Link Explorer) that are currently defined in the Workbench. Through the Link Explorer View you can define new connections, new servers, edit their properties, delete connections and servers and export and import connections and servers. The Default WPS Server One of the defined servers is always set as the default server. There will only be one default server for all connections. This server is shown in bold in the WPS Server Explorer View and the Link Explorer View. The default server is the one that is acted upon by default when, for example, you run a program using the Run toolbar icon. The toolbar icons Run, Stop, Clear Log, Clear Results and Restart Server and their associated keyboard shortcuts all act on the default server. WPS Server Environment The environment maintained by a server is initialised on startup of the server. A typical workstation installation of WPS Workbench will come with a single local server configured that is launched when the Workbench is opened and is terminated when the Workbench is closed down. 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. 35

36 Log output is cumulative and shows information and any errors from each program that has been run during the current session. It can be cleared using the Clear Log option. Listing output, like log output, is cumulative and shows the results of every program run in the current session. HTML output similarly shows the results of programs but is not cumulative. Listing and HTML output can be cleared using the Clear Results option. The server itself can also be restarted, using the Restart Server option. 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 etc that may have been set up on the server. Viewing the Output Generated by the WPS Server The generated. Output Explorer View will display all the log, listing output and HTML result files that have been The Results Explorer View will display a hierarchical list of listing and HTML output. The WPS Server Explorer View will display all the libraries, data sets and file references that are being maintained in the WPS Server environment. Workspace The term Workspace refers to the container that holds your 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. However, projects within a workspace can, but do not necessarily have to reside beneath the parent workspace folder. On Windows, the default location of the workspace when WPS is first installed is your 'My Documents' folder with the following directory structure: WPS Workspaces\Workspace1 On UNIX and Linux platforms the default location of the workspace is the directory that your $HOME environment variable is set to, again with the following directory structure: WPS Workspaces\Workspace1 Please refer to the section in this guide called Switching to a Different Workspace to see how to change the workspace location. Programs A program is a program written in the language of SAS. 36

37 You can create and edit programs in the Workbench using the SAS Editor. This editor uses colour coding to highlight errors and to help distinguish the various keywords, variables, values etc that make up a program. To assist navigation the Workbench displays the structural elements of a program in the Outline View. Quick Difference Indicators As you modify a program, quick difference indicators automatically appear in the left hand white border of the program. They show that something is different in that line of code from when it was last saved. A change has been made to the line of code. If you hover your mouse over this coloured indicator in the left hand border it will display the section of code as it was before you made the change. A new additional line of code. The position where one or more lines of code have been deleted. Note: When you save a program the quick difference indicators will be cleared from the margin. You can navigate between quick difference indicators in an individual program by using the Annotation and Previous Annotation controls. Next Program Names A program can have any name you desire (subject to your operating system's restrictions) but it must have a file extension of.wps or.sas. Files with either of these extensions are handled the same way by WPS and indicate that the file contains a program written in the language of SAS. When Creating a New Program, the Workbench will automatically suggest a new name but you can type in any name you desire. If you do not specify an extension the program will automatically be created with the extension.sas. Working with Multiple Programs You can have as many projects open in your 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 window. For each program that is open, a corresponding program can be given focus in the editor window by clicking on its tab. tab is displayed in the top of the Editor window. An open Program Colours and Layout Colours used to display language elements in a program and various other display and file controls are all Workbench preferences that can be viewed and modified. Colour Coding of Language Elements The colours used to display language elements in a program are controlled by the WPS Syntax Coloring preferences. 37

38 Program Layout The layout of a program, whether to display line numbers, and indeed a whole number of other display controls can all be user defined. Refer to the General Text Editors section for more details. Program Writing and Editing Although it is possible to open a program with various editors provided with the Workbench, only the SAS Editor will provide features specifically for writing and editing language of SAS programs. Help With Language Elements There are several ways that you can get help while you are creating or modifying a program: Refer to the Wps Reference for Language Elements guide supplied with WPS. This is supplied as a PDF file and also can be accessed from the Workbench menu Help > Help Contents > and then selecting Wps Reference for Language Elements from the left hand contents menu of the Help window. Use the context-sensitive help feature to get Dynamic Help for Language Elements, i.e. automatically display a list of relevant topics from the Wps Reference for Language Elements guide. Using Program Content Assist feature to automatically get WPS to finish writing a particular language element. Left Hand Program Border The left hand borders of the Editor view are used to display different features. In the grey border you will see annotations. In the 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. Quick difference indicators are useful for showing you what edits you have made recently to a given line of a program. When you change a line of code a quick difference indicator will appear as a coloured block in the left hand side of the white border to the left of the program editor. If you hover the mouse over this coloured block a popup window will show you what the code looked like before you changed it. Annotations An annotation is a marker displayed in the left hand grey border of a program that is open in the Editor view. The annotations that you may see displayed are: Bookmarks Tasks Search results Adding markers and performing searches is described in Markers. 38

39 You navigate between annotations in an individual program by using the Previous Annotation controls. Next Annotation and Local History The Workbench maintains a the Workbench when using the local history of modifications to programs or other files manipulated in Project Explorer View. 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 Workbench Project Explorer. Note: Local History is not available when managing files through the File Explorer View. History of Edits Each time you save a file in the Workbench, a snapshot of the current contents of the file is added to the Workbench's local history. If you modify a file outside of the Workbench, or modify a file opened with File Explorer, there will be no record added to the history. This history provides the ability to take any of your current programs and Compare with Local History or even to Replace with Local History to take the file back to a previous edited version. Each modification in the local history is uniquely represented by the date and time the file was saved. History of Deletions Each time you delete a program or file using the Workbench's facility to Deleting an Object, via the Project Explorer View, 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 recover or Restore from Local History the item in the project or folder, but also to choose which state from the item's history to restore. Local History Preferences Local History Size and Duration controls how long to keep the local history, how many entries to keep in the history and the maximum file size that can be recorded. Running a Program You can run a program either from inside the Workbench or from a command line outside of the Workbench. However you run a program, they are always executed by the WPS compiler/interpreter. Running 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 execute until the other program has completed. You may, however, register more than one WPS Server, in which case you can have more than one program running concurrently. The state from previous runs is preserved and so subsequent runs can interact with the prior state. 39

40 While the Workbench is open, the output from previous runs is not automatically deleted. In order to clear previous output on a given WPS Server, you can use the WPS > Clear Log or WPS > Clear Results or the relevant toolbar buttons or context menus. Alternatively, to clear all previous output and completely clear the state of a WPS Server, including emptying the WORK library and deassigning all macro definitions and libraries, you can use Restart Server. Running Outside the Workbench When you run a program from a command line outside of the Workbench, the WPS compiler/interpreter is invoked directly. The output files generated by running a program this way cannot be seen inside the Workbench, unless the resulting files are opened manually inside it. More Information For more details on how to actually run programs from inside the Workbench or outside from a command line, please refer to Running Programs. To see how you can list and open the output (i.e. logs, datasets, results, etc) generated from running a program, please refer to Working with Program Output. For details about various preferences that can be specified regarding running programs, please refer to WPS. Managing ODS Output Once you have run a program that produces some output using ODS you can view the results in the Results Explorer View. The management of which ODS destinations WPS outputs to, and the location of the output generated can either be managed by yourself with explicit ODS statements in your code, or you can leave the Workbench to manage the results automatically. The choice as to how you want the Workbench to manage ODS output for you really depends on whether you require complete control of all your output and its location or not. For example, if, in the long term, the program you are running in the Workbench will be run in a batch environment (depending on your environment see Run a Program on the Command Line in Windows or Run a Program on the Command Line in a Non-Windows Operating System) then the program itself will have to control the ODS destinations and locations it writes to. If it does not, it will not function correctly within the batch environment. In this case, you will not want the Workbench to automatically manage results. If you predominantly work day to day with your programs in the Workbench interactively, and are more interested in seeing the results presented in the Workbench, rather than being concerned with where they are written, then automatic management will be a useful feature for you. By default WPS controls results automatically, and sets the default ODS destination to HTML. This setting can be changed by modifying the Result Option preference accessible via Window > Preferences > WPS > Result Options. Please see WPS Result Options for details about the settings available for this preference. 40

41 Analyser Tools The Workbench has tools that can scan existing programs written in the language of SAS. These will generate reports that can help to indicate which of your existing programs written in the language of SAS will run unchanged in WPS, which programs may need some modification, and which programs contain language elements that are vital but not yet supported by WPS. Running Analyses It is possible to analyse single Programs, multiple Projects (via Project Explorer View), or multiple folders (via File Explorer View) containing hundreds of programs. Even when analysing hundreds of programs, an analysis report is often generated in less than a few minutes without the need to actually run the programs or connect to any data sources. Analyse Program Compatibility : To determine if your existing programs or projects contain any unsupported language elements. Analyse Language Usage : To list every single language element that has been used in selected programs or projects. The analysis will indicate which elements are supported and which are unsupported. You can use the Workbench's code analyser on the Windows platform to Analyse Mainframe Programs. Whichever method you choose to analyse your existing programs or projects an appropriate analysis report will be generated and automatically opened in the Workbench. Analysis Reports Program Compatibility Report A program compatibility analysis report contains only details about unsupported language elements used in programs. It does not report any supported language elements that were used in the program(s). This style of report is generated when you Analyse Program Compatibility. Language Usage Report A language usage analysis report contains details about all language elements of the language of SAS that are used in programs, i.e. both supported and unsupported elements. This style of report is generated when you Analyse Language Usage. Related Topics: Analysis Restrictions Opening Analysis Reports Navigating Analysis Reports Export Analysis Results to Excel 41

42 Markers Markers are objects that can be associated with any program. The two types of marker in the Workbench are: Bookmarks Tasks These markers are listed in their respective marker view and also in the left hand margin or gutter of an open program. Bookmarks 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. Note: It is not possible to create bookmarks on files opened from the File Explorer View, unless they are members of a project. This is because files opened outside of Projects may be anywhere in the filesystem, 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 you can either add a bookmark on a particular line within a program, or against an individual program file listed in the Bookmark... from the gutter. Project Explorer View. For lines within a file you can also use the context menu Add You can then list and navigate between all your bookmarks via the Bookmarks View ( Window > Show View > Other > General > Bookmarks). You can even jump between bookmarks in different programs in different projects. Note: If you export a project, the bookmarks are not exported with it. Please refer to the section in this guide called Working with Bookmarks to see how to create, navigate and manage bookmarks. Tasks 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 priority level of high, normal or low. There is no limit to the number of task marks you can add inside a program. Note: You cannot add a task against an individual program file. Note: It is not possible to create tasks on programs opened from the File Explorer View, unless they are members of a project. This is because programs opened this way may be anywhere in the filesystem and tasks can only be set on files that are members of a workspace project. 42

43 You can then list and navigate between all your tasks via the Tasks View ( Window > Show View > Other > General > Tasks). The Tasks view also allows you to change priority levels, edit the description and either un-tick the task. tick or You can even jump between task marks in different programs in different projects. If you export a project, the tasks are not exported. Please refer to the section in this guide called Working with Tasks to see how to create, navigate and manage task marks. Context-Sensitive Help If you encounter a view you do not understand, use the context-sensitive help (ensure the view in question has focus by clicking on it and then press F1 on your keyboard). The Help view will display a short description about the view and list related topics. Leave the Help view open to see information on other Workbench views when you focus on them. Note: After following a link clicking on the Related Topics link (at the top of the Help view) returns to the original context sensitive help page. Otherwise the Help view will not automatically update as you continue to use the Workbench. Dynamic Help for Program Writing When you have a program open, the context sensitive help is also able to offer dynamic help about language elements. Either add a new language element to a program or point to an already written element and the Help view will update to show related topics. Dialogs Dialogs are used in the Workbench to show information or gather user input. File System Operation File System Operations can be initiated via the File Explorer View. A summary of the last performed operation can be found in the Progress View. A link in the view will allow you to display the File System Operation Dialog, to see more detailed information about the most recent operation. Information shown includes: Status : Success or Error Operation : Copy, rename, delete etc. Source : Original location of the file or folder object 43

44 Destination : The target folder or root Exception : Any errors that occurred when the operation was performed. Note: When part of an operation fails, the Workbench will attempt 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 files. Further information For further information on File System Operations, please refer to the following sections: File Explorer View Progress View File Explorer File Management 44

45 Tasks Working with Workbench Views You can manipulate the individual Windows and Views of the Workbench to create your own customized Perspectives. This section of the guide describes how to manipulate the individual views. Opening a View To open a view in the Workbench: 1. Select the menu option Window > Show View. 2. To see a complete list of views, select Other... from the drop-down menu. You will be presented with a list of all the available views grouped under category folders. 3. Highlight the view you wish to open. 4. Press the OK button to complete the task. The view you select will open (if it was not already open) and will automatically be given focus. Its opening position in the Workbench will be the same position that it was in when it was last closed. Closing a View To close a view that is open in the Workbench: 1. Make sure the view is active by clicking on its tab. 2. Click on the close icon in the tab of that view. With the exception of the Editor and Output view, if you close all the views in a particular View Stack, the adjacent view stack expands to take up the space. Resizing a View You have to re-size a View Stack in order to re-size all the views it contains: 1. Move your mouse over the border between two view stacks until the cursor changes to the resize icon. 2. Press your left mouse button and keep it pressed while you drag the border to make it larger or smaller. 3. Release the mouse button to complete the resize operation. Moving a View You will need to understand the View Stack concept before reading this topic. To Start Moving an Individual View or Editor: 45

46 1. Click on the tab header and drag the window to the desired position. When moving a view or window, you have the following options: You can move the view to a new area in the workbench, where there are no views. This will create a new view stack in that location. You can add the view to an existing view stack, and its tab will appear alongside the other views in that stack. You can move the view into a window outside of the Workbench, and detached from it. To move the view to a new area: 1. Drag the view over an existing view stack, where you want your window to appear. 2. The view stack will divide. This represents how the Workbench will arrange the existing view stack and the view you are using. Moving the mouse cursor will make the view divide differently, depending on the dimensions of the view. 3. Drop the view in the division of the view stack where you would like the view to appear. The view will appear where you dropped it, in a new view stack, and the original view stack will reduce in size to accommodate it. To move the view alongside other views: 1. Drag view or editor into the tabbed area on another view stack. A vertical line will appear, indicating where the view will appear if you drop it there. 2. Drop the view. It will then appear in the new position, inside that view stack. To Create a Detached Window Outside the Workbench: 1. Drag and drop the view or editor outside of the Workbench to create an detached window. 2. To put the view back into the main user interface, drag the tab (not the window) back over main Workbench screen. Using a Detached View You can detach from the Workbench window any individual view into its own window. To Detach a View: 1. Click and drag the tab header of the desired View or Editor and drag outside of the main user interface. Drop to create a new window. To Re-Attach a View: 1. Drag the View or Editor's tab (not the window's title bar) in the detached window back over the main Workbench window. Rectangles will appear where the View or Editor will be dropped. 2. Drop the View in the desired position. The detached view should now revert to being docked in the Workbench. Note: If you close a detached view, it will still be detached when you next open it. 46

47 Minimise a Window You will need to understand the View Stack concept before reading this topic. Minimising a window will minimise all the views in the view stack inside that window. This will result in these views appearing as buttons with icons on either the left or right of the Workbench, as seen here: To minimise a window or view: Click on the Minimise button of the relevant window or view Maximise a Window To maximise a window or view so that fills the entire Workbench either: Click on the Maximise button of the relevant window or view Double click on the window's toolbar or the view's tab Maximising a view will make it occupy as much space as it possibly can. When this happens, other views that occupy the same view stack (the view tabs that are close by) are also maximised, but the original view remains on top, and still has focus. All other view stacks will be minimised to the edges of the Workbench window represented as icons. Restore a Window You will need to understand the View Stack concept before reading this topic. Restoring a window or view essentially returns it to its 'normal' state. This will be a member of a View Stack, occupying part of the Workbench Perspective. Views that have either been maximised or minimised can be restored. Minimised views appear as buttons to the left and right extremes of the Workbench application window. To restore a window that has been maximised either: Click on the Restore button of the relevant window or view Double click on the window's toolbar or the view's tab To restore a window that has been minimised either: Right click on the relevant icon in the view stack to see the context menu, then select Restore. All views in the view's current view stack are restored. Click the Restore icon above the minimised view stack to restore the views in that stack. 47

48 Working with Perspectives You can customise any of the supplied swap between any saved perspectives while you are working. Perspectives and save them to create your own. You can also To get the most out customising a perspective, you should also read the section in this guide concerned with Working with Workbench Views to learn how to change the layout and position of individual views and windows within a perspective. This section of the guide describes the various ways you can manipulate perspectives. Resetting a Perspective At any time you can reset a perspective back to its default layout: 1. Select the menu option Window > Reset Perspective. 2. Press the OK button to confirm you want to reset it. Saving a Perspective If you have changed the layout of a perspective, you can save it under a user defined name for future use: 1. Click on the menu option Window > Save Perspective As. 2. You must now give the perspective a name. Either enter a new name or use the name suggested. 3. Press the OK button to continue. If a perspective is already saved with the name you have just entered, you will be asked if you want to overwrite it with the new perspective layout. Note: A perspective gets its icon from the one that you had open when you saved it. Deleting a Perspective To delete a perspective: 1. Click on the menu option Window > Preferences. 2. From the left hand tree view on the Preferences window, select General > Perspectives. 3. From the list of Available perspectives click on the perspective you wish to delete. 4. Select the Delete button to permanently remove the perspective. 5. Click the OK button to close the Preferences window. Note: You can only delete user created perspectives. In other words, you cannot delete a perspective that was supplied with WPS. Opening a Perspective To open a different perspective: 1. Select the menu option Window > Open Perspective. 48

49 2. To see a complete list of perspectives, select Other... from the drop-down menu. You will be presented with a list of all the available perspectives. 3. Highlight the one you wish to open. 4. Press the OK button to complete the task. When you open a perspective, the Workbench will display its name and icon near the top right (by default) of the Workbench. If you have other perspectives open at the same time, they will be listed in this area also so you can click on them quickly to change between them. Closing a Perspective To close a perspective that is open in the Workbench: 1. If you have more than one perspective open, make sure your Workbench is displaying the one you wish close by clicking on its quick button (the default position of open perspective quick buttons is near the top right). 2. From the main menu select the option Window > Close Perspective. Switching Between Open Perspectives If you have more than one perspective open you can quickly switch between them: 1. Locate on your Workbench where the open perspectives are listed. The default position for this list is near the upper right of the Workbench. They are listed with their individual icon and name to the right of the Open Perspective icon. 2. Click on one of the perspectives listed. The Workbench will switch to that perspective. Work the Way You Want WPS will remember when you next open the Workbench, exactly how the windows and views were arranged, etc, when you last closed it. You do not even have to save a perspective to ensure that this happens. This ensures that your favourite the Workbench. perspective is immediately available for you as soon as you open Working with Projects The Workbench has facilities for managing existing Projects and for creating or deleting them. This section of the guide describes how to use these facilities. Note: You can also use the File Explorer View to manage your programs and file resources, if you wish. See the File Explorer File Management topic for more information on this. Creating a New Project To create a new project: 49

50 1. To ensure you can see what happens when you create a new project, make sure you have the Project Explorer view open ( Window > Show View > Other... > General > 2. Select the File > New > Project menu option. You will see the first page of the New Project wizard. 3. Expand the General folder and highlight the Project node. 4. Now select the Next button. 5. Enter the new Project name. Project Explorer). If the name of the new project is not an existing folder, a new folder will be created. If a folder with the same name already exists, it will be used by the new project. 6. (Optional) If you want to change the default location of the new project, clear the Use default checkbox and specify the new Directory. Caution: If you choose a directory outside of the current active Workspace, then be aware that by adding it to the project, you are not moving the folder. It is merely referred to by the project. 7. Click the Finish button to create the new project. Copying a Project You can use the Workbench's Copy and Paste facility to create a new project based on an existing project. For general information about this facility, please refer to the Copying Objects section in this guide. Deleting a Project To delete a project: 1. Ensure you have the Project Explorer view open ( Window > Show View > Other... > General > Project Explorer). 2. Right click on the project and from the popup menu select Delete. 3. A message should be displayed, allowing you to confirm or cancel the deletion. You will see a checkbox option Delete project contents on disk (cannot be undone). Selecting this option will permanently remove the project folder and its contents from the file system. If you opt not to remove the contents from the file system, you can at a later date use the File > Import > General > Existing Project into Workspace feature, to re-display the project in the Workbench. 4. Click the Yes button to proceed with the delete. Closing and Opening a Project When you have multiple open projects in the Workbench, you might like to close some projects to make sure you don't accidentally manipulate the wrong programs. To Close a Project: 50

51 1. Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Highlight the project you wish to close. 3. Now select from the main menu Project > Close Project. 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. To Re-Open a Project: 1. Open the Project Explorer view ( Window > Show View > Other > General > Project Explorer). 2. Highlight the closed project 3. select from the main menu Project > Open Project. Exporting A Project To make a copy or backup of a project and all the files and folders it contains: 1. Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Highlight the project you wish to export. 3. Select the main menu item File > Export. The Export window will open. 4. From the Export window, expand the tree under the General node. 5. Select one of the following Export Destination types: File System - Make a copy of your project folder and the files and sub- folders it contains. Archive File - Create a single compressed zip file in the export location. The Workbench has the ability to read and write zip files without the need for any additional installed software such as WinZip. 6. Click the Next button. 7. (Optional) You can now select or de-select any files and folders that you wish to export. Because you highlighted a project before you began the export process, this is the one selected for exporting along with all the objects it contains. If you want to change your selection, you could click the Deselect All button to make sure nothing is selected and then in the left hand window, tick the project you want to export and 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 To Directory, use the Browse button to select the location where you want to place the export. 9. Click on the Finish button 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 chose in Step 8, you can either see a zip file, or all the copied files and folders. Importing Files or Archive Files To import files from either an archive file (such as a zip file) or from the file system: 51

52 1. You need to import into an existing project. If you do not have an existing project you need to refer to the Creating a New Project section. 2. To start the import process, select the main menu item File > Import. The Import window will open. 3. From the Import window, expand the tree under the General node. 4. Highlight one of the following options: File System Use this if the files and folders to import are not archived in a single file (zip, tar or tar.gz, for example). Archive Use this if the files and folders to import are archived in one file. 5. Click on the Next > button. 6. Now, depending on which option you selected previously, set the From directory or From archive file. Use the Browse button to select the archive file or the location of the folder holding the files you want to import. 7. When you have set the From directory or From archive file, you should see a list of the files and folders that are available to import. Ensure there is a tick next to the objects you wish to import. Tip: You probably do not want to select the parent folder of the files to import, otherwise you will end up with your imported files inside a sub-folder in your new project. Restriction: Do not import a project definition file ( in the project you are about to select in the next step as the 'Into Folder'. 8. Use the Browse button to set the import Into folder. 9. Click the Finish button to continue..project ), otherwise it will overwrite the one Importing an Existing Project To import an existing project into the Workbench: 1. From the main menu select File > Import. The Import window will open. 2. From the Import window expand the tree under the General node. 3. Highlight the Existing Project into Workspace option. 4. Click on the Next > button. 5. Choose one of the following options: Select root directory: Use this if the project is not archived in a single file. (zip, tar or tar.gz, for example). Click the Browse... button to select the folder where the project is located. Select archive file: Use this if the project to import is archived in one file. Click the Browse... button to select the archive file containing the project. 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. 6. Click the Finish button to start the import process. Switching to a Different Workspace To switch to a different Workspace so you can display or create a different group of projects: 52

53 1. So that you can see the outcome of switching Workspaces, first ensure you have the Project Explorer view open ( Window > Show View > Other > General > 2. Select from the main menu File > Switch Workspace > Other. You will see the Workspace Launcher window. 3. Use the Browse button to select a different Workspace. You will see the Select Workspace Directory window. 4. You can now either select an existing workspace or create a new one. Project Explorer). Select an Existing Workspace: If the workspace folder already exists, simply use the tree view to highlight the existing folder. Create a New Workspace: Use the Make New Folder button to create a new workspace folder. You can create a new workspace folder on any drive and/or in any existing directory. 5. Once you have selected which workspace folder to use, click on the OK button to close the Select Workspace Directory window. 6. Click on the Workspace Launcher window's OK button to start the switch. This will cause the Workbench to automatically close and restart with the new workspace. 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 SAS Institute Inc. or earlier versions of WPS and want to use these existing objects with the latest version of WPS. Note: With version 3.1 of WPS onwards, it is no longer a requirement to use Projects to manage your Workbench resources. Using the File Explorer View, any file accessible through the operating system is now available from within the Workbench. You can also make connections to other computers to use programs stored elsewhere. Migrating from Previous Versions of WPS Introduction 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. Furthermore, any existing programs do not need to be modified to work with the latest version of WPS. Typically Projects created with earlier versions of WPS can be opened and used by later versions of WPS without any additional action. Migrating from SAS Software Introduction If you already have Programs written in the language of SAS developed with other products e.g. from SAS Institute Inc, there is no conversion process that you have to undertake in-order to use these programs 53

54 with WPS. Any file with the extension.sas is assumed to be a edit and run. program that the Workbench can open, Accessing your existing programs You can access your existing programs from the File Explorer View. Through this view, it is possible to access any program you have on your local operating system, and you can also connect to other computers to access programs. Alternatively, you may wish to work with Projects in the Workbench. Working with projects through the Project Explorer View allows you some benefits not available with the File Explorer. For help on how to manage your existing program files, see Working with Files And Folders, also in this guide. Check Program Compatibility Before trying to execute your existing programs in WPS it is recommended that you first use the Workbench Analyser Tools to determine if your existing programs in the language of SAS contain any language elements that are unsupported or unknown to this release of WPS. 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 File Explorer View and Project Explorer View. It is also worth pointing out that simply opening Programs in the Workbench will also display unknown or unsupported language elements in red. Note that, although they are generally very accurate, the Analyser Tools are not guaranteed to be 100% accurate due to the nature of the syntax of the language of SAS making this difficult to achieve. Using your Programs in the Workbench For more details on how to use your programs in the Workbench, please refer to the Working with Programs section in this guide. Working with Files And Folders In this section of the guide we will look a little closer at how you can manipulate the various objects that are contained in Projects or in the file system via the File Explorer View. Project Explorer View is ideal where you have a set of files you need to manage from one organised local repository (called a Workspace). You can create one or more Projects in a Workspace to tackle specific tasks. Any kind of local file can be contained in a Workspace, and all operations you would expect to be able to perform on files are available (including the ability to run programs). Workspace objects can be managed with Local History, and they can also be exported to archives or to other folders in the local file system, and such archives may also be imported in this view. 54

55 File Explorer View differs from Project Explorer in that it permits access to all files available to you on your local file system, and also to remote file systems, via Shortcut Directories. Shortcut Directories are similar to Projects and point to folders at any level within the file system on which they are created. Local History is not available when using File Explorer, and neither is Import or Export, but files and folders can be moved between file systems by using copy/cut/paste operations. Table 1. View Options Summary View Open File Run Local Import/ & Edit ManagementprogramsHistory Export Projects and Archives Manage Remote File Systems Manage Local System Full File Project Explorer File Explorer Yes Yes Yes Yes Yes No No Yes Yes Yes No No Yes Yes Project Explorer File Management The objects in Projects have the benefit of Local History to help you manage changes. Creating a New File WPS Workbench allows you to create any type of new file: 1. Select the menu option File > New > File. 2. In the window that opens, select the project or folder where you wish to create the new file. 3. Near the bottom of the window, type in the new file name. File Extensions: If you specify a file extension and it is one that the system knows about (e.g..wps or.sas are treated as a program,.doc is regarded as a Microsoft Word document) then the new file will be associated with the appropriate editor. If no file extension is specified or the extension is not one that the system recognises, the default action is to associate the new object with the WPS Workbench Text Editor. 4. Press the Finish button to complete the task. Closing Files Any file that is opened in the Editor view has a tab labelled with the file name. To stop displaying the file in the Editor, move the mouse over the tab and then selecting the right of the name. close button that appears to the To find out the different ways you can open a file, you should read the Working with Editors section in this guide. 55

56 Creating a New Folder You can have any number of folders and sub-folders in a project. 1. Select the menu option File > New > Folder. 2. In the window that opens, select the project or folder where you wish to create the new folder. 3. Near the bottom of the window, type in the new Folder name. 4. (Optional) Clicking the Advanced button 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 location originally chosen. 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 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 you make to the contents will affect the folder in the 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 (see Working with Local History). Use the Browse... button to choose a folder in your file system to link to. 5. Press the Finish button to complete the task. Moving an Object To move any object from one project to another: 1. Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Move your mouse over the object you wish to move. 3. Press your left mouse button and keep it pressed as you start to drag the object. 4. Release the mouse button to drop the object onto another project or folder that you can see. Tip: You can even drag and drop between Microsoft Windows Explorer and the Workbench Project Explorer. Copying Objects To copy any object from one project to another: 1. Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Click on the object you wish to copy. 3. From the main menu select the option Edit > Copy. 4. Then click on the project or folder where you want to make the new copy. 56

57 5. From the main menu select the option Edit > Paste. 6. Only if you try to paste into the same location that you copied from, you will be prompted to enter a new name. Deleting an Object Deleting an actual project is discussed in Deleting a Project. Their behaviour when being deleted is slightly different to that discussed below. To delete any object from a project: 1. Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Click on the object you wish to delete. 3. From the main menu select the option Edit > Delete. 4. Press OK to confirm you wish to proceed with the delete. Note: If you delete objects using the Workbench Project delete facilities rather than Operating System delete tools, you can use the Workbench feature discussed in Restore from Local History. Note: Files that you work with that are not contained within a Project in the Project Explorer will not be able to use features such as local history. These features rely on the file belonging to a Project. Such Project files are known as "resources" within the workbench. Renaming an Object To rename an object, or even the project itself: 1. Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Click on the object you wish to rename. 3. From the main menu select the option File > Rename. 4. The highlighted object now allows you to type in the new name. 5. Press Enter on your keyboard when you have finished typing. File Explorer File Management In this section of the guide we will look a little closer at how you can manipulate the various objects that are contained in the file system via the File Explorer View. The benefit of using the File Explorer is that you can access files and folders on remote systems as well as local ones. Connections to remote systems can be made using the Link Explorer View. Note: Any files you edit that are not contained within a Project in the Project Explorer will not be able to use features such as local history. These features rely on the file belonging to a Project. Such Project files are known as "resources" within the workbench (see Project Explorer File Management). 57

58 Creating a New File WPS Workbench allows you to create any type of new file: 1. Ensure you have the File Explorer view open ( Window > Show View > Other > WPS > File Explorer). 2. Right-click the container object ( Shortcut Directory or Folder) you want to create the new file in, to show the context menu. 3. Select or hover over the New menu option, and then select the kind of file you want. Available options are as follows: Program will create a named program and open it in the editor. Untitled program will create a new untitled program in the parent folder and open it in the editor. File will create a new file in the parent folder. 4. In the window that opens, you have an opportunity to change the location of the new file. You will see that the container from where you opened the context menu is currently selected. You may choose to create the file on an entirely different connection, if you wish, even a remote connection. 5. Near the bottom of the window, type in the new file name. File Extensions: If you specify a file extension and it is one that the system knows about (e.g..wps or.sas are treated as a program,.doc is regarded as a Microsoft Word document) then the new file will be associated with the appropriate editor. 6. Press the Finish button to complete the task. Creating a New Folder Folders can be created where you have appropriate operation system privileges on your local and remote connections. 1. Ensure you have the File Explorer view open ( Window > Show View > Other > WPS > File Explorer). 2. Right-click the container object ( Shortcut Directory or Folder) you want to create the new folder in, to show the context menu. 3. Select or hover over the New menu option, and then select the Folder sub-menu option. 4. In the window that opens, you have an opportunity to change the location of the new folder. You will see that the container from where you opened the context menu is currently selected. You may choose to create the folder on an entirely different connection, if you wish, even a remote connection. 5. Near the bottom of the window, type in the new Folder name. 6. Press the Finish button to complete the task. Copying an Object You can copy file system objects to folders in your local connection and remote connections. There are several ways to do this, and two of these are explained here. 58

59 Copying with the edit menu You can copy file system objects to folders in your local connection and remote connections: 1. Ensure you have the File Explorer view open ( Window > Show View > Other > WPS > File Explorer). 2. Either right click on the object you want to copy and select Copy, or select it and use the keyboard shortcut for copy for your operating system. 3. Right click the target Shortcut Directory or Folder you want to copy the object to, and click Paste, or select the target and use the keyboard shortcut for the paste operation for your operating system. 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. Copying with drag and drop You can copy file system objects to folders in your local connection and remote connections: 1. Ensure you have the File Explorer view open ( Window > Show View > Other > WPS > File Explorer). 2. Click on the object you wish to copy. 3. Press your left mouse button, and keep it pressed as you start to drag the object. 4. Now, with the left mouse button still pressed, press and hold the Control key on your keyboard. You should notice that a plus symbol (+) appears near the mouse pointer. 5. Keeping both the Control key and left mouse button pressed, drag the object onto a Shortcut Directory or that location. Folder object and release the mouse button, then the key, to perform the copy to 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. Moving an Object You can move file system objects to folders in your local connection and remote connections. There are several ways to do this, and two of these are explained here. Moving with the edit menu You can move File Explorer objects by using the edit menu. 1. Ensure you have the File Explorer view open ( Window > Show View > Other > WPS > File Explorer). 2. Either right click on the object you want to move and select Cut, or select it and use the keyboard shortcut for cut for your operating system. 59

60 3. Right click the target Shortcut Directory or Folder you want to move the object to, and click Paste, or select the target and use the keyboard shortcut for the paste operation for your operating system. 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. Moving with drag and drop You can drag and drop files and folders to move them. 1. Ensure you have the File Explorer view open ( Window > Show View > Other > WPS > File Explorer). 2. Move your mouse over the object you wish to move. 3. Press your left mouse button, and keep it pressed as you start to drag the object. 4. Release the mouse button to drop the object onto another Shortcut Directory or Folder that you can see, to move the object to that location. 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. Deleting an Object You can delete file system objects with the File Explorer: 1. Ensure you have the File Explorer view open ( Window > Show View > Other > WPS > File Explorer). 2. Right click on the object you wish to delete to show the context menu 3. From the menu select the option Delete. 4. Click OK to confirm you wish to proceed with the delete. Progress of the operation can be viewed in the Progress View. Note: If you delete objects using the Workbench Project delete facilities rather than File Explorer, you can use the Workbench feature discussed in Restore from Local History. Renaming an Object To rename a file system object: 1. Ensure you have the File Explorer view open ( Window > Show View > Other > WPS > File Explorer). 2. Right click on the object you wish to rename to show the context menu. 3. Select the Rename option. 4. A window will be shown containing the existing object name. You may enter a new name for the object here. 60

61 5. Press Enter on your keyboard when you have finished typing. Progress of the operation can be viewed in the Progress View. Working with Editors In any of the Perspectives supplied with the Workbench or that you have created, there is always an Editor and Output View. In this section of the guide we will look a little closer at the various ways of opening files with different editors into this view. You can open programs from either the Project Explorer View or the File Explorer View. 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 you are opening. Opening editors with Project Explorer When using the Project Explorer View, you have control over exactly how the Workbench should open your files. The different methods are explained here. SAS Editor The SAS Editor provides features suitable for editing programs (programs written in the language of SAS), such as colour coding of the language elements. Only files with an extension.wps or.sas can be opened in this editor. Programs may either be opened from a Project, or directly from the filesystem. Programs opened from a Project allow additional workbench features to be accessed including local history. However using Projects is not necessarily suitable for all situations. To open a program in the SAS Editor: 1. If your program belongs to a project ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Right mouse click on the program you wish to open. 3. From the popup menu select Open With > SAS Editor. 4. If your program does not belong to a project you can drag a file into the Workbench from the operating system filesystem explorer or other external tool. You can also use the File > Open File... menu option. 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, i.e., no features are available in this editor for colour coding. To open a file in the Text Editor: 1. Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Right mouse click on the file you wish to open. 61

62 3. From the popup menu select Open With > Text Editor. System Editor If a file has an extension registered to an application installed on your computer (e.g..doc may be registered to 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 you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Right mouse click on the file you wish to open. 3. From the popup menu select Open With > System Editor. In-Place Editor The Workbench supports OLE document editors. 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 window and the Microsoft Word's pull-down menu options are integrated into the menu bar of the view. To open a file with the In-Place Editor: 1. Navigate in the Project Explorer to the file you wish to open. 2. Right mouse click on the file. 3. From the popup menu select Open With > In-Place Editor. Default Editor This is the default selection when you double click on a file. When opening the file, the Workbench uses either the application associated with that file type, or the editor last used to open the file. To open a file with the Default Editor: 1. Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Ensure you can see the file you wish to open. 3. Either double click on the file, or right mouse click on the file and from the popup menu select Open With > Default Editor. Opening Editors with File Explorer Opening editors with File Explorer is straightforward, because the Workbench will decide which is the most appropriate editor to use. 1. Ensure that you have the File Explorer View open. 2. Find the file you want to open, and double click it. 62

63 The file will be opened. The editor used to open the files will Program files (.wps and.sas file extensions) are opened in the WPS Editor. Text files (.txt.) are opened in the Text Editor. XML files (.xml) are opened in the Text Editor. HTML files (.html) may be opened inside the Workbench, although this is not available on all platforms. Other files types may also open in the Workbench, but this depends on the Operating System. Note: On some Operating Systems, the Workbench will attempt to open the application associated with the file, if it cannot be opened in the Workbench itself. Working with Programs This section of the guide describes the tools associated with editing and running output they generate. Programs and the Creating a New Program To create a brand new program: 1. Select from the main menu the option File > New > Program. You will see the New Program wizard open. 2. Select the project or folder in which to create your new program. 3. Now you need to give the new program a name. The Workbench will suggest a name such as Program1.sas. If there is already a program using this name, then it will suggest Program2.sas, etc. If you omit the file extension, the workbench will append a.sas extension. If you want to type in another name, you might like to refer to the section in this guide called Program Names. 4. (Optional) Click on the Advanced button and enable the option to Link to file in the file system. Then use the Browse button to select an existing program from any project. Note: This step creates a new shortcut to the existing program. You will not physically have a new program in your project. 5. Press the Finish button to complete the task. You will see the new program appear in the Project Explorer view and it will automatically open in the Editor window ready for you to start typing in code. Opening a Non-Project Program Note: Ensure you have the File Explorer view open ( Window > Show View > Other > WPS > File Explorer). You can open a program that is not in a Workspace by using the File Explorer View: 1. Locate the program in the File Explorer View by navigating the file system until you find the program you wish to open. 63

64 2. Double-click on the program's entry in the File Explorer View. The program will open in the program editor window where you can edit it or simply view its content. Note: Depending on your operating system you may be able to double-click on files in an external filesystem explorer with the appropriate file extension (e.g..sas) to open a file in the Workbench editor. Note: Files not belonging to a Project do not benefit from certain features of the Workbench such as local history. We recommend that where possible files are opened from within a Project. See Opening a Project Program. Opening a Project Program Note: Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). To open a program that belongs to a Project: 1. Expand the tree view of the project containing the program you are interested in, and locate the program in the folder hierarchy. 2. There are two ways to open the file in the editor. Use the context menu Right click the Double-click the program Simply double-click on the program and choose Open With > SAS Editor from the context menu. program's entry in the tree view. The program will open in the program editor window where you can edit it or simply view its content. Note: It is also possible to open files that do not belong to a Project. See Opening a Non-Project Program. Getting Help While Writing Programs There are several ways that the Workbench can offer assistance while you are writing a program. 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, 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, 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 help topic you can see. 3. Click on the search term to perform the search. Relevant topics will be listed in the Help View. You may then select these to assist you with writing your program. 64

65 4. When you have finished reading the help, click on the Related Topics link (at the top of the Help view) to return to the context-sensitive help page or the view will not update automatically as you continue to use the Workbench. Using Program Content Assist The SAS Editor provides a content assist feature that can suggest language elements which you can select and are then automatically typed into your program: 1. Type a word into a program that expects to have more language elements following it. For example type the word PROC After the word type a single space character. 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 expected language elements. 4. (Optional) You can filter the list by typing in the first letter(s) of the language element you think you want to use. 5. Double click on the language element you want and it will appear in your program. Running Programs This section of the guide describes the various ways you can run a before it has completed executing. program and how to cancel a run Run a Program Inside The Workbench There are several ways to run a program inside the Workbench. If you have more than one WPS Server registered in the Workbench, one of the servers will be set as the default. The default server (highlighted in bold) is always shown at the top of the list of Servers in the WPS Server Explorer View. You can run programs on any server, and shortcuts offer a simple and quick way to run them on the default server. Run from the Main Menu To run a program inside the Workbench from the Main Menu: 1. Select the program you want to run by using one of the following methods: in the Project Explorer View or the File Explorer View, highlight the program you want to run. ensure the program you want to run is open in the editor window and has focus. 2. If the program was already open and you have part of the program highlighted, then the selected part will be executed and not the whole program. 3. Execute Run by doing one of the following: From the main menu, select WPS > Run > Local Server or substitute the name of your WPS Server in place of Local Server. Use the CTRL+R keyboard shortcut to run on the default server. 1 (Presently the content assist feature only works for the word PROC) 65

66 While the program is executing, at the bottom right of the Workbench you will see an indication that the run is in progress. Note: For details about various preferences that can be specified with respect to running programs, please refer to WPS. Remember: When you run a program it can interact with other data sets, file references, etc, that have been previously created. To clear the state of the WPS Server you can Restart Server. Run from the Context Menu To run a program inside the Workbench from context menus: 1. Select the program you want to run by one of the following methods: in the Project Explorer View or the File Explorer View, right click the program you want to run. You will then see the context menu. ensure the program you want to run is open in the editor window and has focus, and right click in the editor window. 2. If the program was already open and you have part of the program highlighted, then the selected part will be executed and not the whole program. 3. From the context menu, select Run > Local Server or substitute the name of your WPS Server in place of Local Server. While the program is executing, you will see at the bottom right of the Workbench an indication that the run is in progress. Note: For details about various preferences that can be specified with respect to running programs, please refer to WPS. Remember: When you run a program it can interact with other data sets, file references, etc, that have been previously created. To clear the state of the WPS Server you can Restart Server. Run part of a Program You can select a group of lines in a program and run them: 1. Make sure the program you are interested in is open and has been given focus. 2. Highlight the section of code in the program you wish to run. 3. Execute Run by doing one of the following: From the main menu, select WPS > Run > Local Server or substitute the name of your WPS Server in place of Local Server. Use the CTRL+R keyboard shortcut to run on the default server. Right click in the Editor window and click Run > Local Server from the menu, or substitute the name of your WPS Server in place of Local Server. While the program is executing, at the bottom right of the Workbench you will see an indication that the run is in progress. 66

67 Remember: When you run selected lines from a program they can interact with other data sets, file references, etc, that have been previously created. To clear the state of the Server you can Restart Server feature. Stopping a Run If a program is running and you want to stop it before it has finished executing: 1. From the main menu, select the WPS > Cancel > Local Server option. Substitute server name for Local Server if you are not using the default local server. 2. You can alternatively use the button in the Progress view 3. When the progress indicator in the lower right corner of the Workbench disappears, the program has stopped running. Depending on the particular step that the program is executing, it may not stop immediately. The log will contain a message similar to ERROR: Execution was cancelled. Run a Program on the Command Line in Windows Command Line WPS To run a program from a command line you need to use the application called wps. The executable can be found in the bin directory where WPS was installed. Running wps on its own will not do anything, so you will need to pass it some additional instructions in the following form: wps <options> <programfilename> Please refer to the Command Line WPS section for more details about the <options> that can be specified. Also, the Configuration Files section has more details about configuration files containing system options that are used when you run programs. Windows command line execution By way of an example, if you wish to run a program called 'Program1.sas' that is in the D:\Work\WPS Programs directory. In a command window change directory to where WPS is installed and then to the bin directory. Then type: wps "D:\Work\WPS Programs\Program1.sas" Program Results Generated by wps When a program is run using wps, any results that are generated are automatically captured into a file called <programfilename>.lst. For example if we ran a program called Program1.sas, in the same folder as this program we would end up with a file called Program1.lst that contained the results output. You can open this file with any text editor of your choice. 67

68 Create a batch file to call WPS If you wish to be able to run a program or programs using the same options each time then it is advisable to create a batch file to do this for you. If WPS is installed at C:\Program Files\World Programming WPS 3 and your program, as above, is at d:\work\wps Programs then you could create a batch file called RunPrograms.bat containing : set WPSLOC=C:\Program Files\World Programming WPS 3 set PRJLOC="D:\Work\WPS Programs" "%WPSLOC%\bin\wps" "%PRJLOC%\Program1.sas" One benefit of the way in which the example programs work is that they use fully qualified paths, meaning they can be executed from anywhere on your machine and will still work. Create a Log File When running wps, it is useful to capture the log information so you can check to see if any errors or problems were encountered. This can be accomplished by redirecting 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 then 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 viewed with the text editor of your choice. N.B. redirecting output in this manner will mean that it will not be shown in the terminal it was executed from. Every time you capture the log information into a file with the same name, the file will be re-created. In other words, log information is not appended to the same file; it only shows details from the latest run. If you do wish for the new log to be appended then change the redirection symbol ">" to ">>". For example: "%WPSLOC%\bin\wps" "%PRJLOC%\Program1.sas" >> "d:\work\wps Logs \Program1.log" Tip: Since log files can be too large to look for errors by hand a simple search for error to find out if the program executed correctly. 68

69 Run a Program on the Command Line in a Non-Windows Operating System Command Line WPS To run a program from a command line you need to use the application called wps. The executable can be found in the bin directory where WPS was installed. Running wps on its own will not do anything, so you will need to pass it some additional instructions in the following form: wps <options> <programfilename> Please refer to the Command Line WPS section for more details about the <options> that can be specified. Also, the Configuration Files section has more details about configuration files containing system options that are used when you run programs. Command line execution By way of an example, if you wish to run a program called 'Program1.sas' that is in the /home/user/ programs directory. In a command window change directory to where WPS is installed and then to the bin directory. Then type: wps "/home/user/programs/program1.sas" Program Results Generated by wps When a program is run using wps, any results that are generated are automatically captured into a file called <programfilename>.lst. For example if we ran a program called Program1.sas, in the same folder as this program we would end up with a file called Program1.lst that contained the results output. You can open this file with any text editor of your choice. Create a shell file to call WPS If you wish to be able to run a program or programs using the same options each time then it is advisable to create a shell file to do this for you. Assuming WPS is installed in the directory /tools/wps and your program is located in the /home/ user/programs then you could create a text file RunPrograms.sh containing: export WPSLOC=/tools/wps export PRJLOC=/home/user/programs "$WPSLOC/bin/wps" "$PRJLOC/Program1.sas" N.B. The file will need the correct permissions before being executable. To make this batch file run more than one program, copy the last line and modify it to run the new program. One benefit of the way in which the example programs work is that they use fully qualified paths, meaning they can be executed from anywhere on your machine and will still work. 69

70 Create a Log File When running wps, it is useful to capture the log information so you can check to see if any errors or problems were encountered. This can be accomplished by redirecting the output of the program to a file. For example, to modify the above examples 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 batch file is run the file Program1.log will be in the specified directory and can be viewed with the text editor of your choice. N.B. redirecting output in this manner will mean that it will not be shown in the terminal it was executed from. Every time you capture the log information into a file with the same name, the file will be re-created. In other words, log information is not appended to the same file; it only shows details from the latest run. If you do wish for the new log to be appended then change the redirection symbol ">" to ">>". For example: "$WPSLOC/bin/wps" "$PRJLOC/Program1.sas" >> "/home/user/logs/program1.log" Tip: Since log files can be too large to search for errors by hand, a simple search for error to find out if the program executed correctly often helps. Restart Server If you wish to clear the log, all results, file references, libraries, data sets etc you need to restart the WPS Server. Doing so means that programs will no longer be able to interact with any objects created prior to the restart. Each time you open the Workbench, the WPS Server is automatically restarted. Manual Restart Rather than closing and re-opening the Workbench, you can manually restart the WPS Server: 1. Restarting a server can be instigated in a number of ways: From the main menu, select the WPS > Restart Server > local option. Replace local with your server name if you are not using the default local server. Right click on the required server in the WPS Server Explorer View, Results Explorer View or Output Explorer View and choose Restart from the pop-up menu. Notice: If Show advanced server actions is enabled in WPS preferences, then the singular Restart menu option will not be available. Please read the section below. If it is the default server you are trying to restart, then you can use the keyboard shortcut (by default Ctrl-Alt-S) 70

71 2. A confirmation window may be displayed, allowing you to cancel the restart if you wish. Clicking OK to proceed will clear everything including listing output, HTML output, log, data sets, catalogs, filerefs, etc for that server. Notice: You will not see the confirmation dialog if you have seen the dialog before and have checked the Do not show this confirmation again option. 3. Press OK to proceed with the restart. 4. The items in the Output Explorer view and WPS Server Explorer view will be cleared accordingly. Note: It is possible to just Clear the Log or to just Clearing the Results Output and keep all the other output. Restarting with Advanced Server Actions Warning: This section is only relevant to users who have the Show advanced server actions option enabled in the WPS preferences. If Advanced Server Actions are available, then the context menu for a WPS Server in the WPS Server Explorer View (and other views that have server nodes) will appear a little different. The following options will be avaible for restarting instead of the singular Restart option : Restart, new WORK - Restart and clear all contents of the WORK library (as a normal restart). Restart, keep WORK - Restart and keep all contents of the WORK library. Linking the Active Program with the Project Explorer view If you have several programs from different projects open in the Editor view, you can configure the Project Explorer view to automatically expand a project's contents so that the relevant program in the Explorer's tree view is highlighted every time you select an open program in the Editor view. Restriction: This feature does not work on programs opened with the File Explorer View. 1. Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. From the Project Explorer's button bar, click the Link with Editor button. This will either toggle this feature on or off. Working with WPS Links This section of the guide describes various tasks associated with managing Host Connection and WPS Server definitions. The tasks can be performed via the Link Explorer View. Some can be performed from the WPS > Links menu. Creating a New Remote Host Connection You will need to have access to a UNIX machine with a licensed WPS Server installation. You will need to ensure that you have SSH access to the machine, and that you know the location of the WPS installation 71

72 on that machine. You may need to contact the machine administrator to get this information and to ensure that you have access. You can connect a WPS Workbench running on your workstation to a server copy of WPS running on a supported UNIX platform, and harness the power of that machine to perform computation. For more information on the concepts involved see WPS Server. Note that you don't need any extra software installed in your workstation, in particular you do not need a separate SSH client installation. It can be useful to have an SSH client installed however to independently verify that you can indeed connect to the remote machine using SSH. 1. Open the Remote Host Connection Wizard by doing one of the following: Ensure that the Link Explorer View is visible, and click on the New Remote Connection button. From the main menu, choose WPS > Links > New Remote Host Connection. 2. In the resulting wizard, type in the hostname or IP address of the remote machine to which you wish to connect. If you wish to specify a port other than the default 22, this can be specified in the field provided. The connection name will automatically be changed as you type the hostname to that of the hostname, but you can change the connection name to something more suitable if required (connection names must be unique, so if you are creating multiple connections to the same host you will need to modify the connection name). 3. Enter the user name which you want WPS to make the SSH connection to the remote machine with. 72

73 4. Decide whether you want the connection to be opened now, and whether you want the connection to be opened automatically when the workbench is started by checking the relevant checkboxes. 5. Press Next to define the connection's shortcut directories. Shortcut directories are shortcuts to directories on the remote file system. By default, there are shortcut directories defined for Home (~/) and Root (/). Use the Add... and Remove buttons to edit the list of shortcut directories. Double-click a shortcut to change its definition. 6. If you selected to open the connection immediately, you may be prompted to confirm the identity of the host's RSA fingerprint. If you encounter this dialog, contact your systems administrator. The first time you attempt to connect to a particular host machine you will encounter this message and you will need to confirm the host key with your systems administrator. Once the host key has been confirmed it is stored in the Workbench and subsequent attempts to connection to the same host machine will not require this to be reconfirmed. Assuming that the host key is confirmed by your system administrator, then click Yes. 7. If you selected to open the connection immediately you will now most likely be prompted for a password to authenticate yourself to the host machine. Your systems administrator will have provided you with the required password. Enter this password in the entry box in the Password Required dialog and click OK. There will now be an entry in the Link Explorer view for your new connection. You will now need to add WPS Server definitions to this connection in order to use WPS. Creating a New Local WPS Server The WPS Workbench allows you to have multiple local servers defined on your local connection. For more information on the concepts involved see WPS Server. 73

74 1. Open the New Local WPS Server Wizard by doing one of the following: Ensure that the Link Explorer View is visible, and right-click on the Local Host Connection, and click on the New WPS Server option in the context menu. From the main menu, choose WPS > Links > New WPS Server > Local. 2. In the resulting dialog box, enter a name for the server. This name must be unique across all connections. 3. Choose whether you would like to start the server immediately, and whether you would like to start the server each time the connection is opened. 4. Press Finish to complete the wizard and create the new server definition. There will now be an entry in the Link Explorer View for your new WPS Server. You can then follow the steps in Local WPS Server Properties to configure startup options for the server. Creating a New Remote WPS Server The WPS Workbench allows you to have multiple remote WPS Servers defined on a remote Host Connection. For more information on the concepts involved see WPS Server 1. Open the New Remote WPS Server Wizard by doing one of the following: Ensure that the Link Explorer View is visible, and right-click on the Host Connection you wish to add a server to, and click on the New WPS Server option in the context menu. From the main menu, choose WPS > Links > New WPS Server > Host Connection Name. 74

75 2. In the resulting dialog box, enter a name for the server. This name must be unique across all connections. 3. Enter the path on the remote file-system where WPS is installed. This path will be the root of the installation. 4. Choose whether you would like to start the server immediately, and whether you would like to start the server each time the connection is opened. 5. Press Finish to complete the wizard and create the new server definition There will now be an entry in the Link Explorer view for your new WPS Server connection. You can then follow the steps in Remote WPS Server Properties 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, which can then be imported into another Workspace. 1. Ensure that the Link Explorer View is visible. 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 Using the file selection dialog enter the name of the file that you wish to create. This file will contain the exported connection definitions in XML form. This file will have the extension CDX. The Host Connection definitions will be saved to the selected file. This file can then be distributed amongst your work group, or imported directly into another Workspace on your machine. To import the connection definitions into a workspace see Importing Host Connection Definitions from a File. 75

76 Exporting WPS Server Definitions to a File To simplify sharing server definitions within a work group, or to enable you to copy server definitions between workspaces, you can export WPS Server definitions to a file which can then be imported into another workspace. 1. Ensure that the Link Explorer View is visible. 2. Select the servers that you wish to export from the list in the Link Explorer View. 3. From the right click menu select Export WPS Server definition Using the file selection dialog enter the name of the file that you wish to create. This file will contain the exported server definitions in XML form and will have the extension SDX. The WPS Server definitions will be saved to the selected file. This file can then be distributed amongst your work group, or imported directly into another workspace on your machine. To import the server definitions into a workspace see Importing WPS Server Definitions from a File. Importing Host Connection Definitions from a File This task assumes that you have previously exported some connection definitions to a file, or have been provided with an export file created by someone else in your work group 1. Open the file selection dialog by doing one of the following: Ensure that the Link Explorer View is visible, and click on the Import Host Connection Definition button. From the main menu, choose WPS > Links > Import Remote Host Connection. 2. Using the file selection dialog select the file containing the previously exported connection definitions. Connection definition files (*.cdx) can be imported as well as Server Connections definitions (*.xml) from older versions of WPS. 3. Alternatively, connections can be imported by dragging a Connection Definition File (*.cdx) onto the Link Explorer view. The Host Connection definitions will be imported from the selected file. If there are any name clashes, the imported connection definition will be renamed automatically so that it has a unique name within your list of connections. Importing WPS Server Definitions from a File This task assumes that you have previously exported some WPS Server definitions to a file, or have been provided with an export file created by someone else in your work group. You will also need to have at least one Host Connection already configured, as a WPS Server is associated with a Host Connection. 1. Open the Import WPS Server Definition file selector dialog by doing one of the following: Ensure that the Link Explorer View is visible, select a Host Connection and choose Import WPS Server Definition from the right click context menu. From the main menu, choose WPS > Links > Import WPS Server > Host Connection Name 76

77 2. Using the file selection dialog select the file containing the previously exported server definitions. 3. Alternatively, servers can be imported by dragging WPS Server Definition Files (*.sdx) onto a Host Connection node in the Link Explorer view. The WPS Server definitions will be imported from the selected file. If there are any name clashes, the imported server definition will be renamed automatically so that it has a unique name within your list of WPS Servers. Selecting the Default Server Connection Within the list of WPS Servers that you have defined over all Host Connections, one is always marked as the default server. If you define multiple server definitions you may want to change this default. See The Default WPS Server for more information on the concept of the default server Select the WPS Server that you wish to make the default in the Link Explorer view or WPS Server Explorer view and right click to show the context menu. From the context menu select Set as Default Server. If this option is not enabled, then the selected server is already the default server, or you selected more than one server. The selected WPS Server will now be the default server, and will be shown in bold in the WPS Server Explorer view, and will always appear first in the lists of servers. Working with Program Output This section of the guide looks at the features for locating and manipulating the results (HTML and listing), logs and data sets that are generated as a result of running a program. Working with Logs This section of the guide looks at the features for locating and manipulating the log output. Viewing the Log To display the information contained in the log: 1. Ensure you have the Output Explorer view open ( Window > Show View > Other > WPS > Output Explorer). 2. Right mouse click on the Log node and from the popup menu select Open. 3. Alternatively double-click on the Log node. If you have performed several runs, the previous log information will be concatenated into the existing log text. You can Clear the Log to ensure that when you next run a program, the log only contains information for that run. If the log contains a lot of information, you may refer to the Navigating the Log section in this guide. Tip: You can control how the different items (e.g. errors, warnings, notes, etc) are displayed in a log viewed in the Workbench. Please refer to WPS Log Syntax Coloring preferences for more details. 77

78 If you have more than one WPS Server registered in the Workbench then a separate log window will be opened for each server log that you view. Navigating the Log If you have performed several runs and have not used Restart Server or Clear the Log, then each output will have been appended log in order of execution. To navigate the information contained in the log file: 1. Ensure you are Viewing the Log. 2. Now ensure you have the Outline view open ( Window > Show View > Other > General > Outline). 3. In this view you will see nodes for all previous log entries with the times 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 There are several ways to save the log to a file: 1. Ensure you have the Output Explorer view open ( Window > Show View > Other > WPS > Output Explorer). 2. Right mouse click on the Log node and from the popup menu the Save As... option. 3. Alternatively, open the Log in the editor (see Viewing the Log), and right mouse click on the editor window and select As... menu option. Printing the Log Save As. With the log open in the editor you can also use the File > Save To print the log, open the log file and select 'Print...' from the 'File' menu. Alternatively, right-click on the log file viewer itself and select Print... or right-click on the Log in the Output Explorer and select Print Log... Clear the Log To clear the contents of the log: 1. From the main menu, select the WPS > Clear Log option. 2. The log file will now be blank. Tip: You can use the keyboard shortcut Ctrl + Alt + L Tip: If you have only one WPS Server registered as is normally the case with a standard workstation installation of WPS Workbench, then the Clear Log action will always clear the log for that server. Tip: If you have more than one WPS Server registered then the Clear Log menu action will clear the log for the default server unless a different server or server log is selected and has focus. If in doubt use the tooltip for the toolbar button to show which log will be cleared. 78

79 Working with Listing Output This section of the guide looks at the features for locating and manipulating the listing output. Viewing the Listing Output To view the listing output: 1. Ensure you have the Output Explorer view open ( Window > Show View > Other > WPS > Output Explorer). 2. Right mouse click on the Listing node and from the popup menu select Open. 3. Alternatively double-click on the Listing node. The listing output will open and be given focus. If you have performed several runs, the previous listing output will be concatenated into one listing file. If you wish to clear the listing then you can use: Clear Results (which will also clear any HTML output) Restart Server (which will clear the log, all results, data sets, library and file references etc.) If you have more than one WPS Server registered in the Workbench then a separate listing window will be opened for each server listing that you view. Navigating the Listing Output To navigate the output contained in the listing file: 1. Ensure you are Viewing the Listing Output. 2. Now ensure you have the Outline view open ( Window > Show View > Other > General > Outline). 3. In this view you will see nodes for the various procedures and tables that are contained in the listing output file. 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 you can see the Output Explorer View. To add this view to the current perspective, select the menu item Window > Show View > Other > WPS > Output Explorer. 2. Right-click the listing node and click Save As... in the context menu. You will see a file save dialog allowing you to save the listing. Tip: Alternatively, with the listing itself open (see Viewing the Listing Output), right-click on the listing window and select Save As. Printing the Listing Results Printing the listing output can be achieved in four different ways. First ensure you have the listing view open, and that it has the focus, then: 79

80 1. Right click in the view. From the pop up menu choose Print. 2. Press Ctrl-P (Cmd-P on MacOS). 3. Use the menu option File > Print. 4. Right-click the Listing in the Output Explorer and select Print Results... Working with HTML Output This section of the guide looks at the features for locating and manipulating the HTML output. Viewing HTML Output To view HTML output: 1. Ensure you have the Output Explorer view open ( Window > Show View > Other > WPS > Output Explorer). 2. Expand the WPS Server node for which you wish to view output, so you can see the HTML node. 3. Right mouse click on the HTML node and from the popup menu select Open. 4. Alternatively double-click on the HTML node. The HTML output file will open and be given focus. If the HTML output contains a lot of information, you may want to refer to the Navigating HTML Output section in this guide. Navigating HTML Output If you have performed several runs and have not used Restart Server or cleared the HTML output, the previous HTML output will be available. If you have opted to have the HTML output automatically managed by the Workbench (the default) then each run will create a new HTML file. The outline view of the HTML output provides access to all HTML output created in this way. To navigate the output contained in the HTML file: 1. Ensure you are Viewing HTML Output. 2. Now ensure you have the Outline view open ( Window > Show View > Other > General > Outline). 3. In this view you will see nodes for the various procedures and tables that are contained in the HTML result file. 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. Open the HTML output that you wish to print in the Workbench editor. You can use the outline view to select the part of the HTML file you wish to print. 2. Right mouse click on the editor window and select Print. The standard operating system print dialog window will open. 80

81 3. Alternatively, with the HTML output open in the editor you can use the main menu option File Print. The standard operating system print dialog window will open. 4. HTML output can also be printed by right-clicking the results in the Output Explorer and selecting Print Results... from the pop-up menu. Note: A single HTML output file is created for each run within the Workbench. You can only print the HTML output of one run at a time. See Running a Program for more information about runs. Clearing the Results Output To clear all the results output: 1. From the main menu, select the WPS > Clear Results option. 2. All listing output and HTML output will be cleared. Tip: You can use the keyboard shortcut CTRL + ALT + O Tip: If you have only one WPS Server registered, as is normally the case with a standard workstation installation of WPS Workbench, then the Clear Results action will always clear all results for that server. Tip: If you have more than one WPS Server registered then the Clear Results menu action will clear all the results for the default server unless a different server is selected and has focus. If in doubt use the tooltip for the toolbar button to show which results will be cleared. Working with Data Sets This section of the guide looks at the features for locating and manipulating data sets. Viewing the Contents of a Data Set To display the observations contained in a data set: 1. Ensure you have the WPS Server Explorer view open ( Window > Show View > Other > WPS > WPS Server Explorer). 2. Expand the tree view under the Libraries node until you can see the data set node you wish to open. 3. Right mouse click on the data set node and from the popup menu select Open. 4. Alternatively double-click on the data set node. Tip: You can display labels in the column headers of a data set you are viewing in the Workbench. Please refer to WPS Data Set Viewer preferences for more details. Clearing the Data Sets You cannot just clear the data sets on there own. The process to clear data sets, unavoidably means that you also end up clearing all the other output such as the HTML output, listing output, log entries, libraries, file references, etc. 81

82 In order to clear all the output, you need to use the Restart Server feature. Analysing Programs and Language Elements This section of the guide describes how to use the various Analyser Tools and Analysis Reports. Analysis Restrictions Restrictions on Using The Analyser Tools You do not have to worry about the connection or availability of any data sources as the code analyser does not actually execute programs to perform an analysis and generate a report. The analyser will still report on the syntax you use for data connectivity, etc. You can use the Workbench's code analyser on the Windows platform to Analyse Mainframe Programs. Restrictions on Language Elements Analysed and Reported The code analyser will not report on incorrect syntax or on language elements that are unknown in the language of SAS. Although WPS does support the use of macro language elements and library engines (data access), the analysis reports presently do not contain information on these particular items. For a complete list of the macro language elements and the library engines and options that are supported by this release of WPS, please refer to the Macro Processor and Library Engine sections in thewps Reference For Language Elements guide. When generating Program Compatibility Analysis Reports, if the analyser encounters an unsupported procedure, it just reports that as a problem and does not report on any of that particular procedure's options that have been used. However, when generating Language Usage Analysis Reports, the same unsupported procedure is reported along with any unsupported options that were also encountered. Although WPS Workbench cannot be used on a mainframe the Language Analyser can still be used to check programs for this operating system. Analyse Mainframe Programs The code analyser is a feature of the Workbench and cannot therefore be used on platforms on which the Workbench is not supported. However, if Programs are moved from a Mainframe to a system running the Workbench, the code analyser is still able to report on all language elements including those specific to the z/os platform. When programs are moved from a mainframe to a non-mainframe (distributed) system, note that before the program can be analysed you need to ensure that: Any line numbers have been removed All programs are converted from EBCDIC to ASCII Each program file is given a file extension of.sas 82

83 Refer to the Analysis Restrictions section for more details about analysing your programs. Once you have moved your Mainframe programs to the Windows platform, you can either Program Compatibility or Analyse Language Usage. Analyse Analyse Program Compatibility To analyse one or more programs to see if the language elements they contain are supported in this release of WPS: 1. Use a Workbench view to find the files you wish to analyse: Use the Project Explorer View. You open this view from the main menu via Window > Show View > Other > General > Project Explorer Use the File Explorer View. You open this view from the main menu via Window > Show View > Other > WPS > File Explorer 2. Select the files you wish to analyse: Either, highlight one or more programs. You can select programs from different projects or folders. Or, highlight one or more projects or folders to analyse all the programs within. 3. Right mouse click over any of the highlighted items and from the popup menu select Analyse > Program Compatibility. When the analysis has finished, a the Workbench. Program Compatibility Analysis report will automatically open in Related Topics: Analysis Restrictions Navigating Analysis Reports Export Analysis Results to Excel Analyse Language Usage To report on all the supported and unsupported language elements used in one or more programs: 1. Use a Workbench view to find the files you wish to analyse: Use the Project Explorer View. You open this view from the main menu via Window > Show View > Other > General > Project Explorer Use the File Explorer View. You open this view from the main menu via Window > Show View > Other > WPS > File Explorer 2. Select the files you wish to analyse: Either, highlight one or more programs. You can select programs from different projects or folders. Or, highlight one or more projects or folders to analyse all the programs within. 3. Right mouse click over any of the highlighted items and from the popup menu select File > Analyse > Language Usage. 83

84 When the analysis has finished, a Workbench. Language Usage Analysis report will automatically open in the Related Topics: Analysis Restrictions Navigating Analysis Reports Export Analysis Results to Excel Opening Analysis Reports An analysis report can only be opened by virtue of performing one of the following types of analysis: Analyse Program Compatibility Analyse Language Usage Depending on the type of analysis you perform, the end result is to automatically open either a Compatibility Analysis report, or a Program Language Usage Analysis report. Both types of report will only display the results of the latest analysis. In other words, you cannot have open more than one of each type of analysis report. Once you close an analysis report, it is lost until you either re-run the analysis again or you Export Analysis Results to Excel. Navigating Analysis Reports Drilling Down to Subset Pages Drilling Down: If you move your mouse over an item in the report and your cursor changes to a pointing hand, then the item can be clicked. A single mouse click will drill down to display a subset page of results specific to that item. Drilling Back Up On a subset page, there is always an underlined link at the top of the page that you can click to drill back up to the previous page. Expanding and Collapsing Report Sections Expanding: If you see an the report. Collapsing: If you see an section of the report. icon to the left of a title, you can click on this to expand that section of icon to the left of a title, you can click on this to collapse (or hide) that Opening Programs From a Report When you drill down to one of the lowest subset pages of a report, the page will always display a list of locations where the language element occurs in a program. Click on one of these locations to open the appropriate program at the line where the language element occurs. 84

85 Export Analysis Results to Excel The results of an analysis can be exported to a Microsoft Excel Spreadsheet: 1. Ensure you have an analysis report open in the Workbench as a result of performing one of the following: Analyse Program Compatibility Analyse Language Usage 2. Ensure you are looking at the first page of the analysis report. 3. At the top of the first page, click on the Export results to Excel option. You will see the Save As window open. 4. Enter the desired File name and select where you want to create the Excel spreadsheet. Working with Markers The Workbench has two types of marker that you can work with, bookmarks and tasks. Working with Bookmarks The Workbench has facilities that allow you to add Bookmarks inside a program. The Workbench provides you with tools to create, manage and navigate between bookmarks. This section of the guide describes how to use these facilities. Adding a Bookmark Within a Program To add a new bookmark on a particular line within a program: 1. Open a program in the Editor window using the Project Explorer View. 2. Move your cursor into the grey border ( not the white border) immediately to the left of the line you wish to mark. 3. Right mouse click and from the popup menu select Add Bookmark. 4. You will need to enter a name/description for future reference. Notice how the line of code is the default description. 5. Press OK to finish. You will now see in the border a bookmark tag. Deleting a Bookmark To delete a bookmark: 1. Open the Bookmarks view ( Window > Show View > Other > General > Bookmarks). 2. If you click on the bookmark's description, the Workbench will assume you are trying to edit it. So, for this step, right click on the bookmark. 3. From the popup menu select Delete. 85

86 Navigating Between Bookmarks To navigate between the various bookmarks (i.e. display the program at the appropriate line in the editor window): 1. Open the Bookmarks view ( Window > Show View > Other > General > Bookmarks). 2. Right mouse click anywhere on the bookmark line and from the popup menu select Go To. Double clicking on the line will also open it. 3. The program will open (if it was closed) and be given focus on the Workbench. Working with Tasks The Workbench has a facilities that allow you to add Tasks inside a program. The Workbench provides you with tools to create, manage and navigate between task marks. This section of the guide describes how to use these facilities. Adding a Task To add a new task mark on a particular line within a program: 1. Open a program in the Editor window. 2. Move your cursor into the grey border ( not the white border) immediately to the left of the line you wish to mark. 3. Right mouse click and from the popup menu select Add Task. 4. Enter a description. Notice how the line of code is the default description. 5. Enter a priority level (high, normal or low). 6. Press OK to finish. You will now see in the border a task mark. Deleting a Task To delete a task: 1. Open the Tasks view ( Window > Show View > Other > General > Tasks). 2. If you click on the task description, the Workbench will assume you are trying to edit it. So, for this step, right click on the task in a column other than the description. 3. From the popup menu select Delete. Navigating Between Tasks To navigate between the various task marks (i.e. display the program at the appropriate line in the editor window): 1. Open the Tasks view ( Window > Show View > Other > General > Tasks). 2. Right mouse click anywhere on the task line and from the popup menu select Go To. Double clicking on the line will also open it. 86

87 3. The program will open (if it was closed) and scroll to the appropriate line. Working with Local History The Workbench maintains a Local History about the edits and deletions of programs within Projects manipulated in the Workbench. This history can be used to compare or even revert to previous versions of the same program. This section of the guide discusses using this feature. Note: Local History is not available when managing files through the File Explorer View. Compare with Local History To compare a current saved program with a previous version: 1. Select the program you want to investigate: Either use the Project Explorer view and highlight the program or open the program and make sure it has been given focus. 2. Right click on the program and from the popup menu select Compare With > Local History. The Compare with Local History window will open. You will see a list of revisions of the program. 3. From the list of revisions, double click a particular revision to compare with. The date and time of the revision is shown to help you choose. The current version and previous version are displayed with the differences highlighted. 4. Use the Select Next Change and Select Previous Change buttons to jump between the differences. 5. Click the OK button when you have finished comparing. Note: Local History is not available when managing files through the File Explorer View. Replace with Local History To revert a program in a project back to a previous saved version: 1. Select the program you want to replace: Either, use the Project Explorer view and highlight the program. Or, open the program and make sure it has been given focus. 2. Right click on a program and from the popup menu select Replace With > Local History. The Compare window will open. 3. The window shown will have a list of revisions. Double click on a particular revision to compare with the current version. The current version and previous version are displayed with the differences highlighted. The current version is titled Workspace File, and the revision you selected is titled Local History. 87

88 4. Use the Select Next Change and Select Previous Change buttons to jump between the differences. 5. (Optional) You could just highlight and copy a portion of text from a previous version and then press the Close button in the window's upper right hand corner. Now you can paste your piece of text into another program. 6. Click the Replace button to complete the task. Tip: You cannot use the Replace with Local History features with any file that does not belong to a Workbench Project. Note: Local History is not available when managing files through the File Explorer View. Restore from Local History A program or any other file that has been deleted using the Workbench's delete facility can be undeleted: 1. Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Right click on a folder or project and from the popup menu select Restore from Local History.... The Restore from Local History window will open. 3. Select the checkbox next to the program you want to undelete. 4. If you don't want to undelete just the last state of the program, highlight the program and then you can select any other edition from the are grouped by date. The bottom pane of the dialog shows the contents of the state. 5. Click the Restore button to proceed with the undelete. local history list on the right hand side of the dialog. Revisions Note: Local History is not available when managing files through the File Explorer View. Local History Size and Duration By default, the Workbench keeps seven days of local history for each individual Project program and a maximum of fifty entries per program. There is also a default of 1 MB of storage allocated for each program's local history. All of these settings can be changed and are discussed in the General Local History preferences section. Note: Local History is not available when managing files through the File Explorer View. 88

89 WPS Tips and Tricks Using ODBC : Learn how to use an ODBC connection in a program. WPS Data Set Viewer: Make your data sets display labels for column names. WPS Server Properties: Override any default server options set when you startup the Workbench. WPS WORK Location: Change the system option for the WORK location. WPS Server LOCALE Setting: Change the system option for the LOCALE value. 89

90 Reference License Key WPS requires a valid license key to operate. Only when a license key has been applied will you be able to use WPS to run any programs written in language of SAS. A license key is provided in a separate file to the WPS software installation file and will have a name similar to YourCompanyName_v2-0_Win32.wpskey. This section of the guide looks at how you can apply a new licence key or how to look up the details of the license key that is already applied to your installation. Applying a License Key To apply a new license key to your WPS installation: 1. Select the Workbench menu item Help > Apply License. The Apply License window will be displayed. 2. Click on the Import from file... button. 3. Locate your license key file and then select the Open button. You should see the contents of the license key file displayed. 4. Select the Finish button to apply the license. Attention: If you are using a Microsoft Windows operating system, before applying a license key, ensure you have administrator privileges on your computer. Viewing Your Applied License Details To view the details of the license key that has been applied to your WPS installation: 1. Select the Workbench menu item Help > View License. The License Key information window will be displayed. 2. When you wish to close this window, click on the OK button. Preferences There are many user settings, controls and defaults that you can adjust and specify from the Window > Preferences panel. In this section of the WPS guide we will focus on those preferences that have an effect on how Programs are edited, displayed, run, etc. Any preference that is not described in this WPS guide can be looked up in the Eclipse specific Workbench User Guide. 90

91 Preference 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. By way of an example, type into this box the word log one letter at a time and see how the preference window filters the available pages who's title contain the text you have typed in as a filter. To stop filtering, click on the in the tree view. Clear button and you will see all available preference items re-displayed General Under Window > Preferences > General are controls that not only affect Programs, but also affect other types of files and other general aspects of the Workbench. Here are some of the items that you can control that have an effect on programs: Always Run in Background: Some operations such as running a program, or refreshing a project containing a lot of files, can take a long time to execute. When the Run in Background option is enabled, it allows such tasks to execute without displaying the Executing dialogue window. If this option is left unchecked, the dialog box that appears when running a program has a button that will run that program in the background. Show heap status: When this option is selected the amount of memory that WPS Workbench is using appears in the bottom right corner of the window. Open Mode: This preference controls the way you open on objects in the Workbench with either a single click or a double click of your mouse. General Local History Under Window > Preferences > General > Workspace > Local History are the controls that you can set regarding the Local History. Days to Keep Files: The number of days that you want to keep records for any one program. For example, if you type 20, then a history of saved states from the last twenty days would be kept. The default value is 7 days. Maximum Entries per File: The number of states to keep for any one program. When you exceed the number of entries per file, the oldest changes are discarded to make room for the newer changes. The default is 50 entries per file. Maximum File Size (MB): The maximum file size (in MB) of a program for which a local history should be kept. If the size of the program exceeds the maximum amount of file size allocated, no local history is kept for it. The default size is 1MB. 91

92 General Text Editors Under Window > Preferences > General > Editors > Text Editors you can set the properties of editors. This affects the editing or viewing of Tab Width Undo history size Colours (current line, foreground, background, etc) Show line numbers programs. Some examples of these properties are: Note: Details about the colours used to display language elements in a program can be looked up or defined under the WPS Syntax Coloring preferences. General Text File Encoding In order to display and save programs and files that contain non English characters, you may need to set an appropriate text file encoding value. This can be done at a global level or at a project level. Setting Encoding at a Global Level To set an encoding value at a global level that is used by all projects and therefore by all programs: 1. Select the menu item Window > Preferences. The Preferences window will be displayed. 2. In the left hand menu, expand the General > Workspace node. 3. On the right of the window, you should see controls for setting the Text File Encoding value. For English systems, this is usually set to UTF Enable the Other text file encoding option and select your desired value from the drop down list of available values. 5. Now, select the OK button to apply your change. Note: You may want to also specify an appropriate WPS Server LOCALE Setting. Setting Encoding at a Project Level To set an encoding value only for programs contained in a specific project: 1. Ensure you have the Project Explorer view open ( Window > Show View > Other > General > Project Explorer). 2. Click on the desired project. 3. From the main menu select the option File > Properties. The Properties window for the selected project will be displayed. 4. On the left of the Properties window, ensure the Resource option is selected. 5. On the left of the window, you should see controls for setting the Text File Encoding value. The default option selected is Inherited from container(x), where (x) would be the value set at a global level as described above. 6. Enable the Other text file encoding option and select your desired value from the drop down list of available values. 7. Now, select the OK button to apply your change. 92

93 Note: You may want to also specify an appropriate WPS Server LOCALE Setting. WPS Under Window > Preferences > WPS are the controls that control some general aspects of the WPS Workbench behaviour: Save all modified files before running a program: This preference 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 for this option is Prompt. This causes a dialog to be shown whenever you attempt to run a program. If you have a complex program that consists of a number of source files then it is recommended that this preference be set to Always. Consider the case where you might have two source files and the first uses a %INCLUDE statement to include the contents of the second. This is one method in which a large program can be built up from a number of smaller source files. In this case the %INCLUDE will read the contents of the file as they appear on the disk, and any unsaved changes that you might have in the program editor will not be seen by your program. When you are editing a program and run it using the Run button however, it is the current content of the editor window that is submitted, and not the contents of the file, so unsaved changes will be executed. Close all open data sets before running a program: Sets how WPS deals with closing open data sets when running a program. The behaviour can be one of: Always, Never or Prompt. The default for this option is Prompt. Having data sets open in the data set viewer can cause problems if you attempt to run a program that will overwrite the same open dataset with a new version. For this reason it is recommended that this option be set to Always, to avoid such problems. Show log when an error is encountered running a program: Sets 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 a prompt to be shown the first time an error is encountered in a running program. Close all open datasets when deassigning a library: Controls whether WPS will automatically close any data sets that may be open in a library when you deassign a library by selecting the item from the context menu in the Delete WPS Server Explorer view. The behaviour can be one of: Always, Prompt. The default for this option is Prompt which will cause a prompt when you attempt to deassign a library and there are data sets open. Confirm deletions: This option controls whether WPS will ask for confirmation when you use the Delete item from the context menu in the WPS Server Explorer to do one of the following actions: delete a server definition to delete a data set, catalog or view from within a library to deassign a library to deassign a fileref to delete a catalog entry from with a catalog Confirm server restart: This option controls whether WPS will ask for confirmation when you select a server in the WPS Server Explorer and restart the server from the context menu. 93

94 Autoscroll the log: This option controls whether WPS will automatically scroll the log view or not. Autoscroll the listing: This option controls whether WPS will automatically scroll the listing view or not. Temporary File Location: Contains the directory location where the Workbench will store temporary files. The log files created during execution of a program are stored in this directory, as are any ODS HTML results generated by a program. You may find that you need to modify this setting if the default value points to a location with space restrictions. Log files created during execution can be large, and you may find you encounter space problems. Show advanced server actions: This option controls the context menu options available when restarting WPS servers. If checked, extra options appear in the context menu of a WPS server in several of the Workbench views. These allow you to restart and keep the contents of your WORK library, or to perform a restart that will clear it (as is normal). WPS Code Injection Under Window > Preferences > WPS > Code Injection are the controls that allows for code to be run automatically before and after any program. Enable custom pre-code injection: When this option is enabled the code in the following text box is executed before any program is run. This option provides a facility similar to the INITSTMT system option, except here the code is automatically run before each program that is submitted. The INITSTMT system option is only processed on server startup. The preferences page WPS Result Options controls whether code is automatically injected to set up ODS destinations so that you can easily view the results of your programs in, for example, HTML. However the set up that it performs may not be suitable for you, and in that case you can use the custom code injection facility here to set up ODS destinations in a more suitable way. Enable custom post-code injection: When this option is enabled the code in the following text box is executed after any program is run. This option provides a facility similar to the TERMSTMT system option, except here the code is automatically run after each program that is submitted. The TERMSTMT system option is only processed on server shutdown. WPS Code Templates Window > Preferences > WPS > Code Templates is used to allow code shortcuts to be entered. 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 Ctrl+space and the code completion feature will match temp against the list of code templates, find your template called template1 and substitute it with whatever you defined as the substitution text for the template. If there are more than one code template whose names start temp then you will be presented with a selection dialog to choose which template you would like to substitute. The substitution pattern 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 data set whose 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. 94

95 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. WPS Data Set Viewer Under Window > Preferences > WPS > Data Set Viewer you can set your default preferences concerned with viewing a data set in the Workbench. Show labels for column names: Toggle on/off the option to display labels in the column headers of a data set that is viewed in the Workbench rather than the column names. WPS File Explorer Under Window > Preferences > WPS > File Explorer are the preferences you can set regarding how the file explorer behaves. Select Show hidden files and folders to ensure that files and folders starting with a '.' character (for UNIX based systems) or hidden Windows files/folders are displayed. Hidden files and folders on a remote Windows based system will not be affected by this preference switch. WPS Result Options Under Window > Preferences > WPS > Result Options are the controls for controlling output types Automatically Manage Result Types: If this preference is set to No then there will be no ODS (Output Delivery System) destinations set up by default, and all procedure output will come out in the LISTING destination. This behaviour reflects what happens when you run a WPS program from an operating system command line using the wps executable. You may want to use this setting if you have programs that are ultimately designed to be run from the command line and set up their own ODS destinations. If this preference is set to Yes, then the Workbench will automatically manage ODS destinations based on the check boxes that are ticked in the Result Types section. The destinations are activated by injecting relevant ODS statements before and after each program is submitted. Note: Even if automatic management is chosen it is still possible to define custom ODS destinations as usual. WPS Syntax Coloring Under Window > Preferences > WPS > Syntax Coloring are controls you can specify regarding how to display the language items contained in a program (e.g. data lines, comments, formats, etc). For each different type of language item contained in a program, you can specify attributes for Color, Background Color and if the item should be displayed in Bold. WPS Log Syntax Coloring Under Window > Preferences > WPS > Log Syntax Coloring are the preferences you can set regarding how to display the different items contained in a log file (e.g. errors, notes, warnings, etc). 95

96 For each different type of item contained in a log, you can specify attributes for Color, Background Color and if the item should be displayed in Bold. Backing Up Your Preferences To save your preferences to a backup file, use the File > Export > General > Preferences feature. To import preferences from a backup file, use the File > Import > General > Preferences feature. Editing and Navigating There is a wealth of tools and functions provided by the Workbench to help with editing and navigating about Programs. In this section of the guide we will look at some of the more commonly used features. Undo and Redo Your Edits You can undo program edits step by step by using the main menu option Edit > Undo (or press CTRL + Z on your keyboard). You can step through re-doing any undone edits by using the main menu option Edit > press CTRL + Y on your keyboard). Redo (or Find You can find any text string in an individual program that you have open by using the main menu option Edit > Find/Replace (or press CTRL + F on your keyboard). This feature also allows you to do a find and replace within the open program. Navigate Back and Forward The main menu options Navigate > Back and Navigate > Forward are analogous to the back and forward buttons on a web browser: Back navigates to the previous resource that was viewed in an editor window. Forward navigates to undo the effect of the previous Back command. Unlike a web browser, when you close and re-open WPS Workbench, it still has the navigational information. Go To Your Last Edit The main menu option Navigate > Last Edit Location will automatically do the following: Open a program (if it is closed). Highlight the line you last edited. 96

97 Place your edit cursor at the end of the piece of text you edited. Next and Previous Annotation Although the menu items Next Annotation and Previous Annotation would appear to imply that this feature is for annotations only, you can actually use these controls to navigate between annotations and quick difference indicators in any individual program that is open in the Editor view. What is an Annotation? An annotation is a marker in the left hand grey border of a program: Bookmarks Tasks Search results What is a Quick Difference Indicator? A quick difference indicator in the left hand white border of a program shows that something is different in that line of code from when it was last saved: A change has been made to the line of code. A new additional line of code. The position where one or more lines of code have been deleted. Navigating Between Annotations and Quick Difference Indicators You can navigate between annotations in an individual program that is open by using the main menu options Navigate > Next and Navigate > Previous (or press the respective keyboard options CTRL +. and CTRL +,). As well as using these menu and keyboard options, you can also use the buttons in the Workbench's main button bar for Next Annotation and Previous Annotation. Configure Which Markers and Indicators To Navigate Between 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 which marks and indicators you want to navigate between. Host Connection Properties There are many properties that you can set and adjust that help specialise how a Host Connection behaves. The properties available differ slightly depending on whether your connection is local or remote and whether the connection is currently open or not (see WPS Server for more information about local and remote connections). Connection properties are accessed by selecting the connection you wish to change the properties of in the Link Explorer View, then by right clicking and selecting Properties from the context menu. 97

98 Depending on whether your connection is a local or remote, please continue by selecting the relevant topic below. Local Host Connection Properties The following properties and information are available for a local connection. Shortcut Directories (available for open connections only): A local Shortcut Directory is a shortcut to a directory on the local file-system. The local Shortcut Directories that are created by default differ depending on the operating system you are running the Workbench on: For 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 Shortcut Directories by default. For other operating systems, there will be only 'Home' and 'Root' shortcuts created by default. Other shortcuts can be added, edited and removed from this property page. Shortcut Directories can be explored from the File Explorer view. Note: For Windows users, local Shortcut Directories may only be created if the Local Server component has been installed. Remote Host Connection Properties The following properties and information are available for a remote connection. The list of items on the left of the Properties dialog are explained below. Some items are only available when the server is running, and where that is true it is noted in the sections below. 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. 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 the ssh connection uses ssh port forwarding to send standard in and out information between the remote connection and the workbench or not. 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 get 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 exists at some point, then you can uncheck this check box and the Workbench will allow you to save the settings. Otherwise you will get an error and will be required to specify a host that exists. 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 98

99 server is being started. An example would be the environment variables required in order to use a database library engine. Typically this will 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 may not always be desirable. An alternative is to put any required environment variables into a dedicated shell script and "source" it before invoking the remote server executable. So for example if you were to put the environment modifications into a shell script called ~/wpsenv.sh, then in the Advanced Connection Options page you can put. ~/wpsenv.sh into the text box on this page. Any commands you enter here are invoked before the remote server is executed. The initial. here is necessary to ensure that a sub-shell is not used to invoke the shell script, and that the environment variables that are set by the ~/wpsenv.sh shell script affect the environment of the remote server process. The output from any commands that you execute in this way can be seen in the Console View Shortcut Directories (available for open connections only): A shortcut directory is a shortcut to a directory on the remote file-system. By default, there are shortcut directories defined for your home directory (~/) and the file-system root directory (/). Other shortcut directories can be added, edited and removed from this property page. Shortcut Directories can be explored from the File Explorer view. WPS Server Properties There are many properties that you can set and adjust that help specialise how the WPS Server behaves. The properties available differ slightly depending on whether your server is local or remote (see WPS Server for more information about local and remote servers). Properties are accessed by selecting the server you wish to change in the Link Explorer View, then by right clicking and selecting Properties from the context menu. Depending on whether your server is a local or remote server please continue by selecting the relevant topic below. Local WPS Server Properties The following properties and information are available for a local server. The list of items on the left of the Properties dialog is explained below. Some items are only available when the server is running, and where that is true it is noted in the sections below. Environment: This lists the environment variables that are set on the local machine. This is not modifiable here and is purely for information. This item is only available when the server is running. Launch Options: This section permits you to specify any environment variables that you would like set before the server is started. By clicking the New button you can specify an environment variable name and the value you would like it set to. The item will then appear in the list. You can also then Edit... and Remove any environment variables you have created. 99

100 License Information: This shows the setinit information for the server, such as the products that are licensed, the amount of grace or warning time on the license, and the date that the license expires. This item is only available when the server is running. Macro Variables: This lists the macro variables and their values that are set on the local WPS Server. This is not modifiable here and is purely for information. This item is only available when the server is running. Software: This lists information about the local WPS Server itself, such as its version and the operating system it is running on. This is not modifiable here and is purely for information. This item is only available when the server is running. Startup Options: The server can be configured to start automatically when its connection starts by selecting Start the server automatically on connection startup. The Initial current directory for server process entry is where you to specify the working directory for the server. This is where the server considers itself to be running from and can affect things like where output is generated to or, for example, 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 System Options pane is where you can specify any WPS options that you would like to pass the server to process on startup. The options available here are typically any of those that can be passed directly to WPS on the command line. If you click Add... you will see a new popup dialog that allows you to set options. Clicking the 'Select...' button will present a list of available options. Scroll through to find the one you want, select it, and click OK. You will then be able to set the option value (below the option name), and then click OK to save it. The value chosen is then visible in the local server properties dialog. You can also Remove any options you have set from this dialog. System Options: This lists the names of all the system options that are set on the server along with their values. This is the same information you would get if you ran a PROC OPTIONS statement. This is not modifiable here and is purely for information. This item is only available when the server is running. Remote WPS Server Properties The following properties and information are available for a remote server. The list of items on the left of the Properties dialog are explained below. Some items are only available when the server is running, and where that is true it is noted in the sections below. Environment: This lists the environment variables that are set on the remote machine. This is not modifiable here and is purely for information. This item is only available when the server is running. License Information: This shows the setinit information for the server, such as the products that are licensed, the amount of grace or warning time on the license, and the date that the license expires. This item is only available when the server is running. 100

101 Macro Variables: This lists the macro variables and their values that are set on the remote WPS Server. This is not modifiable here and is purely for information. This item is only available when the server is running. Software: This lists information about the local WPS Server itself, such as its version and the operating system it is running on. This is not modifiable here and is purely for information. This item is only available when the server is running. Startup Options: The server can be configured to start automatically when its connection starts by selecting Start the server automatically on connection startup. The Working directory for execution entry is where you to specify the working directory for the remote server. This is where the server considers itself to be running from. This can affect things like where output is generated to or, for example, 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 System Options pane is where you can specify any WPS options that you would like to pass the server to process on startup. The options available here are typically any of those that can be passed directly to WPS on the command line. If you click Add... you will get a new popup dialog that lists all the options that can be set. Select the option you wish to set and click OK and you will see it added to the list. You can then edit the value of the option. You can also Remove any options you have set. System Options: This lists the names of all the system options that are set on the server along with their values. This is the same information you would get if you ran a PROC OPTIONS statement. This is not modifiable here and is purely for information. This item is only available when the server is running. WPS Server LOCALE Setting The locale used by WPS is set individually by server. Local and remote server properties are set using the same method. To set the language system option for LOCALE that you wish to use for each server: 1. In the WPS Server Explorer pane, place the cursor over the relevant local or remote server. Right click and select the Properties item in the popup menu. The Properties window will be displayed for the selected server. 2. In the left hand menu of the Properties dialog, select the Startup Options node. 3. On the right of the window, you should now be able to select the Add... button. The Startup Option window will be displayed. 4. Click the Select... button on the right of the Name text box, to see a list of available options in a Select Startup Option window. 5. Scroll down and double click on the LOCALE option. The Startup Option dialog will then show your choice. 101

102 6. Type the value you wish to use into the Value text box below the option name, and then click OK. A list of valid LOCALE values can be found in the seperate guide entitled WPS Reference for Language Elements in the Appendix > LOCALE Values section. 7. Now, select the OK button on the Properties window and you will be prompted to restart the server to apply your changes. Note: In order to display and save programs and other files that contain characters for your selected LOCALE, you may need to set an appropriate General Text File Encoding value. Note: 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. When using Command Line WPS to run programs in batch mode, then the startup option is ignored and the LOCALE option in the external config file is used instead. WPS WORK Location To set the language system option for the WORK location that you wish to use every time you startup local or remote server: 1. In the WPS Server Explorer pane, place the cursor over the relevant local or remote server. Right click and select the Properties item in the popup menu. The Properties window will be displayed for the selected server. 2. In the left hand menu of the Properties dialog, select the Startup Options node. 3. On the right of the dialog, you should now click on the Add... button. The Startup Option dialog box will be displayed. Hit the Select... button and the Select Startup Option dialog will be displayed, listing the available system options. 4. Scroll down in the Startup Option list and click on the WORK list item and click the Ok button. The option WORK should now be listed in the Name: entry back in the Startup Option dialog box. 5. Type in the full pathname where you would like to locate your WORK folder in the Value: entry box and then select the OK button. You should now see the WORK option and it's associated value listed in the Startup System Options panel of the Properties dialog. 6. Finally, select the OK button on the Properties dialog and you will be prompted to restart the server to apply your changes. Note: 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 Command Line WPS to run programs in batch mode, then the startup option is ignored and the WORK option in the external config file is used instead. Using ODBC Although this guide is primarily concerned with topics regarding how to use the Workbench features, this section is about using the language element libname within a program. It has been included in this guide for convenience to readers. For full details of the libname language element, please consult the WPS Reference For Language Elements guide. 102

103 ODBC can be used to connect many different types of data source. By way of an example we will discuss how to use it to connect to a DB2 source. First, outside of WPS, set up the local DB2 client (either just a client or full DB2) to make the connection to the remote DB2. Then set up a local ODBC datasource and configure it with that DB2 connection. Now in a program, you can type the following statement: libname lib ODBC dsn=<odbc-datasource-name> user=<userid> pwd=<password>; You can then refer to tables in the user's schema by just saying, for example: data people; set lib.employee; This example will copy the table called employee from the user's schema to a local data set called people. You would now be able to browse the local data set from the Workbench. WPS also supports a schema option on libname: libname lib ODBC dsn=<odbc-datasource-name> user=<userid> pwd=<password> schema=<myschema>; and then when you say: data people; set lib.employee; it refers to the table in the myschema schema. Command Line WPS Besides being able to use WPS in Workbench mode (i.e. from the graphical user interface), you can also use the system in command line mode. This provides a way of running programs outside of the Workbench which is often referred to as running in batch mode. You cannot compile programs into run-time jobs. To use WPS from a command line you need to execute wps.exe on Windows, or wps on any of the Unix based platforms. This executable is located in the bin directory of the WPS installation. The following examples assume a Windows environment, hence the use of wps.exe. wps.exe <options> <programfilename> The <options> can be a list of either: -optionname [optionalvalue] 103

104 -config <configfilename> -set <envvarname> <envvarvalue> Programs When you run a program using wps, the <programfilename> should always be the last parameter you define. In fact, when wps executes, the first parameter that is encountered which does not start with a dash (-) will be considered to be the name of the program to run. Options To explicitly set a system option to use with wps, you should specify: wps.exe -optionname [optionalvalue] <programfilename> You can pass as many optionname system options to wps as you desire. You can only pass wps single valued options on the command line. It 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 the file explicitly referenced when executing wps: wps.exe -config <configfilename> <programfilename> Please refer to the Configuration Files section for a more detailed discussion about configuration files and the order in which they are processed. Note: When running program using wps, any WPS Server Properties that have been setup as a preference under the graphical user interface, will be 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 wps only allows single valued values on the command line. It does not allow parentheses. Output Log Information: When you run a program with wps, the log information about the run is automatically sent to the DOS window in which WPS is running. Once the program has finished running and the DOS window closes, this log information is lost. To capture the log information you need to send it to an external file: wps.exe <options> <programfilename> > <logfilename> 104

105 Capturing the log information in this way means it will no longer be displayed in the DOS window as the program is running. Every time you capture the log information into a file with the same name, the file will be re-created. In other words, log information is not appended to the same file; it only shows details from the latest run. 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 we would get a file called Program1.lst if we ran a program called Program1.sas. You can open this results file with Windows Notepad. Example of Using command Line WPS An example of how to use wps to run a program can be found in this guide under the sections Run a Program on the Command Line in Windows and Run a Program on the Command Line in a Non-Windows Operating System. Configuration Files Configuration files are files that contain system options that control the initial WPS environment. Configuration files are used during WPS initialisation when WPS is run from the command line, and when the Workbench is being used. A configuration file is a simple text file that you can open in a text editor to add, remove or change system options to suit your needs. There is a base configuration file that is included with the WPS installation, called wps.cfg and it is located in the directory where WPS is installed. It is recommended that this file be left untouched and one of the override mechanisms below be used if any modifications need to be made. A number of configuration files can be processed during WPS initialisation, each of which may set some of the same options. If an option is set in more than one place the last one processed will have precedence. Options set on the command line, or options set in the Startup Options configuration panel for a server will override any settings that are set in the configuration files. WPS Initialisation Procedure for Windows When WPS is invoked, the following initialisation procedure occurs: 1. WPS checks the operating system environment variable WPS_SYS_CONFIG. If it exists then the specified configuration file is processed first. The processing of this file doesn't affect whether the default configuration files are loaded. 2. Any files specified via the -config option on the command line, or specified in the Startup Options configuration panel for a server will be processed next. If any configuration files are specified in - config options in this way, then the default configuration files listed below are not loaded, and instead the process jumps straight to the processing of WPS_USER_CONFIG (step 4). Note that overriding the default configuration file processing, specifically the loading of the wps.cfg file in the WPS installation directory must be done with care. There are many required options in the base wps.cfg file. If you choose to use the -config option it is recommended that you either take a copy of the base wps.cfg file 105

106 and modify it to suit, or you make sure to include the base wps.cfg file in your customer configuration file and then override any settings you need, for example: -set wpshome 'somewhere' -config!wpshome/wps.cfg /* And now set any options you want */ 3. Then WPS checks for a number of default configuration files. These are processed in the following order: a. wps.cfg in the WPS installation directory b. My Documents/My WPS Files/.wps.cfg c. My Documents/My WPS Files/wps.cfg d. My Documents/My WPS Files/.wpsv3.cfg e. My Documents/My WPS Files/wpsv3.cfg f. wps.cfg in the current directory g. wpsv3.cfg in the current directory 4. WPS checks for the environment variable WPS_USER_CONFIG. If it exists then the specified configuration file is processed. 5. WPS checks for the environment variable WPS_OPTIONS. If it exists, then any options that are specified in WPS_OPTIONS are processed. The syntax of this environment variable is the same as if the options are specified on the command line. 6. Any options specified on the command line are then processed. WPS Initialisation Procedure for UNIX platforms When WPS is invoked, the following initialisation procedure occurs. 1. All configuration files specified via -config options on the command line or in the Startup Options configuration panel for a server are processed first. If any configuration files are loaded in this way, then the list of default configuration variables in step 4 are not loaded. 2. WPS then checks the WPS_OPTIONS and WPS_V3OPTIONS environment variables for -config options and processes those files. If any configuration files are loaded in this way, then the list of default configuration variables in step 4 are not loaded. Note that this step is skipped if the -NOCONFIG option is specified on the command line. 3. WPS then checks the following environment variables, and if they exist loads the configuration files named by them (the environment variables are expected to name a single configuration file each): a. WPS_CONFIG b. WPS_V3CONFIG If any configuration files are loaded in this way, then the list of default configuration variables in step 4 are not loaded. Note that this step is skipped if the -NOCONFIG option is specified on the command line. 4. Assuming that no configuration files have yet been loaded, the list of default configuration files is loaded. The following files are loaded in the order shown: wps.cfg in the WPS installation directory wps_local.cfg in the WPS installation directory. This file can be edited to provide site specific overrides of various options. 106

107 .wps.cfg in your home directory wps.cfg in your home directory.wpsv3.cfg in your home directory wpsv3.cfg in your home directory wps.cfg in the current directory wpsv3.cfg in the current directory 5. WPS checks for the environment variable WPS_OPTIONS. If it exists, then any options that are specified in WPS_OPTIONS are processed. The syntax of this environment variable is the same as if the options are specified on the command line. 6. WPS checks for the environment variable WPS_V3OPTIONS and processes it in the same way. 7. Any options specified on the command line are then processed. There are also so-called "restricted" configuration files that will always be processed. Any options in these files cannot be changed by any other method. The files are based on the user's userid and groupid. For example if the user is <user> and the group is <group> then the following configuration files will be processed: misc/rstropts/rwps.cfg in the WPS installation directory misc/rstropts/groups/<group>_rwps.cfg in the WPS installation directory misc/rstropts/users/<user>_rwps.cfg in the WPS installation directory Getting Information About the Startup Procedure It is possible to check which config files have been processed by checking the CONFIG system option. You can do this by invoking a simple PROC OPTIONS statement as follows: proc options option=config; run; When using the Workbench you can get the information in the following way. Ensure that you have the WPS Server Explorer View open and right click on the WPS Server icon and choose Properties from the pop-up menu. In the Properties dialog, choose System Options and you will see the values of all system options for the server. Scrolling down to CONFIG will show all the configuration files that were used. You can also set the VERBOSE system option on the command line, or in the Startup Options configuration panel for a server and WPS will generate information in the normal log output indicating which configuration files were processed and which system options were set. To set the VERBOSE option in the workbench, take the following steps. From the Startup Options screen it is possible to change the values that System Options will be set to when the Workbench is loaded. For example: 1. Open the Properties for the relevant server. 2. Select Startup Options from the list of available pages on the left hand side. 3. Click Add Click the Select... button (next to the Name text box). 5. Scroll down the list and find the VERBOSE option and click OK. 107

108 6. Click on the dropdown box next to Value and change the value to VERBOSE (or NOVERBOSE to turn the option off). 7. Click OK. 8. Click OK once again in the properties dialog. 9. A message box will appear stating that the change will not occur until the server is restarted. Click Yes to perform the restart. 10.Check the log (see Working with Logs) and the change to the VERBOSE option means that the processed configuration files and the system options will be shown there when the Workbench starts. AutoExec files AutoExec files are programs that are automatically executed when WPS is started. This can be used for an number of purposes e.g. setting up common libnames so that they do not need to added to each program that is run. When using the Workbench the file will be executed when WPS is first launched and each time the server is restarted. The Workbench also offers the chance to have code that is run before and/or after each program. Please see WPS Code Injection for more details. Specifying an AutoExec file WPS will automatically look for a file called autoexec.sas in a number of directories depending on your operating system. Windows WPS will look in the follow directories: (current directory) My Documents paths specified in the PATH environment variable the root directory of the current drive e.g. C:\ the directory where WPS is installed Other operating systems WPS will look in the follow directories: (current directory) $HOME the directory where WPS is installed Specifying a different file If you wish to automatically run different file, or a file that is in a non-standard directory, then this can be achieved by setting the AUTOEXEC system option, via Configuration Files. If using the Workbench then it can also be done using server properties. Ensure you have the Output Explorer View or Results Explorer View open and right click on the Properties from the pop-up menu. WPS Server icon and choose 108

109 From there choose Startup Options from the dialog box that is shown then : Click Add... Click the Select... button (next to the Name text box). Select the AUTOEXEC option and click OK. Click on the text box next to Value and then type the path to the file that you wish to be used. Click OK. Click OK once again in the properties dialog. A message box will appear stating that the change will not occur until the server is restarted. Click Yes to perform the restart. Once the server has been restarted then the file you have specified will have been executed. Please note that if a default autoexec.sas is found and executed then the AUTOEXEC system option will be changed to point to that file. Welcome Pages About The welcome pages display introductory information about WPS Workbench. They are designed for new users, to help with the understanding of basic WPS concepts. The initial page shows a number of links to other welcome pages. Simply click on the link you are interested in to navigate to that section. Closing and Opening the Welcome Pages To close the welcome pages and use the Workbench, simply click the Close button. You can re-open the welcome pages at any time by selecting the menu item Help > Welcome. Other Controls Located near the top right of the welcome pages are 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. Similar to the 'Back' button in a web browser. Navigate to next topic: Go forwards to a previously viewed topic (after going back). Similar to the 'Forwards' button in a web browser. 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 along-side the other open windows. 109

110 Maximize: Expand the welcome pages to fit the entire Workbench and hide any other open windows. 110

111 Legal Notices General Acknowledgements World Programming Limited is not associated in any way with the SAS Institute WPS is not the SAS System The phrase "language of SAS" used in this document is used in a generic way to describe the computer language often called "the SAS language" or simply "SAS" Trademarks WPS and World Programming are registered trademarks or trademarks of World Programming Limited in the European Union and other countries. (r) or indicate European Community registration. SAS and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. indicates USA registration. MXG is a trademark of Merrill Consultants All other trademarks are the property of their respective owner Third-Party Notices WPS includes software developed by third parties. More information can be found in the THANKS or acknowledgments.txt file included in the WPS installation. 111

112 Reporting problems Known issues There are currently no known critical issues with WPS Workbench. If you encounter problems please follow the instructions below. Getting support How you access technical support for your WPS software depends on how you purchased your software. You can rest assured that WPS always comes with maintenance and support. If you made a standard purchase of WPS software you will have an annual subscription license that entitles you to unlimited free upgrades throughout the twelve months, and free support via support@teamwpc.co.uk. We always respond promptly to support and will do our best to work within an acceptable timescale. Larger customers may have additional support arrangements in place. In this case we may often provide access to our online Issue Tracking System. Your organisation may have nominated super users through which all technical support requests are handled. Resolutions to problems may include suggested workarounds or may require you to update your WPS software installation. Due to the complex nature of the language of SAS it may require some interaction between World Programming and you to identify and resolve the cause of the problem. Stack Trace If an error occurs within the WPS Server then you will see a messagebox informing you that the server has terminated unexpectedly. It will also open the Console View and display the stack trace in red, looking something like the following: 112

113 The text in red is what would need to be highlighted and passed on as part of the troubleshooting process. WPS Server Log Files For certain types of issue you may be requested to provide the log files that are produced by the WPS Server or by the Workbench. Where they are found depends on which operating system you are using: Windows Log Files The server log file is stored in your current workspace. By default this will be in My Documents\Wps Workspaces\Workspace1. Under this is another directory called.metadata containing the file that is simply called.log. Non-Windows Log Files The server log file is stored in the workspace that is currently being used by the Workbench. If your username is <username> then, by default, this will be in /home/<username>/wps Workspaces/ Workspace1. Under this, there is another directory called.metadata containing the file that is simply called.log. Please note that because.metadata and.log start with a period they will normally be hidden and you will need to ensure you can see these types of files. On a command line using the command ls - la will list every file in the directory whether hidden or not. If using a graphical interface then edit your preferences to show hidden and/or backup files. 113