workbench user guide wps workbench user guide w… · workbench user guide version 3.2 8 wps server...

Workbench user guideVersion 3.2

WPS Workbenchuser guide

“To help guide you through using WPSWorkbench to create, edit and run

programs”

Version: 3.2.6Copyright © 2002-2018 World Programming Limited

www.worldprogramming.com


2

Contents

Introduction...............................................................................................7About This Guide........................................................................................................................... 7About WPS.....................................................................................................................................7Users of SAS® Software............................................................................................................... 8

Getting Started....................................................................................... 10Workbench Basics........................................................................................................................10WPS Components........................................................................................................................11Cheat Sheets................................................................................................................................12

Concepts................................................................................................. 17Eclipse.......................................................................................................................................... 17Workbench....................................................................................................................................17Perspectives................................................................................................................................. 17

WPS Perspective...............................................................................................................18View Stack.........................................................................................................................19

Views............................................................................................................................................ 20Help View.......................................................................................................................... 20Project Explorer View........................................................................................................20Link Explorer View............................................................................................................ 21Properties View................................................................................................................. 23Outline View...................................................................................................................... 23Output Explorer View........................................................................................................ 24Results Explorer View....................................................................................................... 25File Explorer View............................................................................................................. 26WPS Server Explorer View............................................................................................... 28Editor View........................................................................................................................ 30Progress View................................................................................................................... 30Bookmarks View................................................................................................................31Tasks View........................................................................................................................ 31Search View...................................................................................................................... 31Console View.....................................................................................................................32

Projects.........................................................................................................................................32Project Definition File........................................................................................................ 33Working with Multiple Projects.......................................................................................... 33

WPS Link......................................................................................................................................33Host Connection................................................................................................................ 33WPS Server.......................................................................................................................34

Workspace....................................................................................................................................35Programs...................................................................................................................................... 36

Program Names................................................................................................................ 36


3

Working with Multiple Programs........................................................................................37Program Colours and Layout............................................................................................ 37Program Writing and Editing............................................................................................. 37Local History......................................................................................................................38Running a Program........................................................................................................... 39Managing ODS Output......................................................................................................39

Libraries........................................................................................................................................ 40Datasets........................................................................................................................................40Analyser Tools..............................................................................................................................41

Analysis Reports................................................................................................................41Markers.........................................................................................................................................42

Bookmarks......................................................................................................................... 42Tasks..................................................................................................................................42

Context-Sensitive Help.................................................................................................................43Dialogs..........................................................................................................................................43

File System Operation.......................................................................................................43

Tasks....................................................................................................... 45Working with Workbench Views.................................................................................................. 45

Closing a View.................................................................................................................. 45Resizing a View.................................................................................................................45Moving a View...................................................................................................................45Using a Detached View.....................................................................................................46Minimise a Window........................................................................................................... 46Maximise a Window.......................................................................................................... 47Restore a Window.............................................................................................................47

Opening a View............................................................................................................................47Working with Perspectives........................................................................................................... 48

Resetting a Perspective.................................................................................................... 48Saving a Perspective.........................................................................................................48Deleting a Perspective...................................................................................................... 48Opening a Perspective......................................................................................................49Closing a Perspective........................................................................................................49Switching Between Open Perspectives............................................................................ 49Work the Way You Want.................................................................................................. 49

Working with Projects...................................................................................................................50Creating a New Project..................................................................................................... 50Copying a Project..............................................................................................................50Deleting a Project..............................................................................................................50Closing and Opening a Project......................................................................................... 51Exporting a Project............................................................................................................51Importing Files or Archive Files........................................................................................ 52Importing an Existing Project............................................................................................ 52Switching to a Different Workspace..................................................................................53

Migrating Existing Programs or Projects......................................................................................53Migrating from Previous Versions of WPS........................................................................54


4

Migrating from SAS® Software......................................................................................... 54Working with Files And Folders...................................................................................................55

Project Explorer File Management....................................................................................55File Explorer File Management......................................................................................... 58

Working with Editors.................................................................................................................... 61Opening files with Project Explorer...................................................................................61Opening files with File Explorer........................................................................................ 63

Working with Programs................................................................................................................63Creating a New Program.................................................................................................. 63Opening a Program that is outside of a Project............................................................... 64Opening a Program that is inside a Project......................................................................64Getting Help While Writing Programs............................................................................... 64Running Programs.............................................................................................................65Restart Server................................................................................................................... 70Linking the Active Program with the Project Explorer view...............................................71

Working with WPS Links..............................................................................................................72Creating a New Remote Host Connection........................................................................72Creating a New Local WPS Server.................................................................................. 75Creating a New Remote WPS Server.............................................................................. 76Exporting Host Connection Definitions to a File............................................................... 77Exporting WPS Server Definitions to a File...................................................................... 77Importing Host Connection Definitions from a File........................................................... 77Importing WPS Server Definitions from a File.................................................................. 78Selecting the Default Server Connection.......................................................................... 78

Importing Datasets....................................................................................................................... 78Importing Datasets From Files..........................................................................................79Importing Spreadsheet Data............................................................................................. 81

Exporting Datasets....................................................................................................................... 82Working with the Dataset Viewer.................................................................................................83

Opening a Dataset............................................................................................................ 84Editing a Dataset...............................................................................................................84Filtering the Dataset View................................................................................................. 89Sorting a dataset............................................................................................................... 91Organising the Dataset View............................................................................................ 91

Working with Program Output......................................................................................................93Working with the Log........................................................................................................ 93Working with Listing Output.............................................................................................. 94Working with HTML Output...............................................................................................96Clearing the Results Output..............................................................................................97Working with Datasets.......................................................................................................97

Analysing Programs and Language Elements.............................................................................98Analysis Restrictions..........................................................................................................98Analyse Mainframe Programs........................................................................................... 98Analyse Program Compatibility......................................................................................... 99Analyse Language Usage................................................................................................. 99Opening Analysis Reports...............................................................................................100


5

Navigating Analysis Reports........................................................................................... 100Export Analysis Results to Excel.................................................................................... 101

Working with Markers.................................................................................................................101Working with Bookmarks.................................................................................................101Working with Tasks......................................................................................................... 102

Working with Local History........................................................................................................ 103Compare with Local History............................................................................................ 103Replace with Local History..............................................................................................103Restore from Local History............................................................................................. 104Local History Size and Duration..................................................................................... 104

WPS Tips and Tricks...........................................................................105

Reference.............................................................................................. 106License Key................................................................................................................................106

Applying a License Key...................................................................................................106Viewing Your Applied License Details............................................................................ 106

Preferences.................................................................................................................................106Preference Filter.............................................................................................................. 106General............................................................................................................................ 107General Local History......................................................................................................107General Text Editors....................................................................................................... 107General Text File Encoding............................................................................................ 108WPS.................................................................................................................................109WPS Code Injection........................................................................................................ 110WPS Code Templates.....................................................................................................110WPS Dataset Viewer.......................................................................................................111WPS File Explorer...........................................................................................................111WPS Result Options........................................................................................................111WPS Syntax Coloring......................................................................................................111WPS Log Syntax Coloring.............................................................................................. 112Backing Up Your Preferences.........................................................................................112

Editing and Navigating............................................................................................................... 112Undo and Redo Your Edits.............................................................................................112Find.................................................................................................................................. 112Navigate Back and Forward............................................................................................112Go To Your Last Edit...................................................................................................... 113Next and Previous Annotation.........................................................................................113

Host Connection Properties....................................................................................................... 113Local Host Connection Properties...................................................................................114Remote Host Connection Properties...............................................................................114

WPS Server Properties..............................................................................................................115Local WPS Server Properties......................................................................................... 115Remote WPS Server Properties..................................................................................... 117WPS Server LOCALE Setting.........................................................................................118WPS WORK Location..................................................................................................... 118


6

Using ODBC...............................................................................................................................119Command Line WPS..................................................................................................................120Configuration Files..................................................................................................................... 122AutoExec files.............................................................................................................................125Datagrid Filter Expressions........................................................................................................ 126Welcome Pages......................................................................................................................... 128

Reporting Problems.............................................................................129

Legal Notices........................................................................................130


7

Introduction

About This GuideOverview

This user guide is intended to help you get started with the World Programming System (WPS). It isdesigned to guide new users through the WPS user interface, with which you can create, edit and runprograms written in the language of SAS.

This user guide does not aim 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.• Teach you every option within WPS. However, once you have worked through this guide you should

be sufficiently familiar with the system to write your own programs and to begin processing andanalysing 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 thereare also toolbar buttons and context menu options available for many WPS options. Menu and buttonoptions 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 WPSOverview

The World Programming System (WPS) fundamentally consists of two components:

• a Graphical User Interface (GUI)/Integrated Development Environment (IDE) known as WPSWorkbench.

• a compiler/interpreter. This can be run from the command line (CLI) and is used to execute existingprograms (sometimes referred to as running WPS in batch mode). When using WPS Workbenchthe compiler is run as a server process (known as WPS Server) and is used to process and executeprograms.


8

WPS Server

WPS Server provides the ability to read and run programs. WPS Server cannot be launched directly; itis launched by WPS Workbench during operation.

WPS Workbench

The GUI/IDE, known as the Workbench, provides facilities to manage, create and edit programs andthen to run programs with the WPS Server.

The Workbench uses Eclipse, originally written by IBM and now part of an open source project, as theframework for the GUI.

WPS Workbench is an extension of Eclipse specially designed to allow users to edit and run programswritten in the language of SAS. It is worth noting that WPS intentionally leaves the Eclipse environmentopen for advanced users to plug-in other third-party tools and facilities for source control, Javadevelopment, 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 toas features of WPS for simplicity. WPS not only inherits functionality from Eclipse but also has speciallydesigned features and controls to aid program development and use.

WPS and SAS® Software

WPS supports programming elements from the language of SAS. This means that programs developedin 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® SoftwareOverview

If you are accustomed to using other products related to the language of SAS such as softwareproduced by SAS Institute Inc, you will find that the language support in WPS is familiar. You canexpect 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 ithandles, or displays objects. You will find that the Workbench has help and reference material to assistyou 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 writefrom and to data files used by SAS software. WPS has a wide selection of library engines to allow youto connect to many leading third-party databases.


9

WPS also uses a proprietary data file format known as WPD. As the default dataset library engine,WPD datasets are used for the WORK library. Because it is the native dataset library engine to WPS, ithas 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 tohelp determine if any existing language of SAS programs you have contain unknown or unsupportedlanguage elements.

Please refer to the help guide entitled WPS Reference for Language Elements for details on the syntaxof 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 existingprograms within WPS Workbench, you should refer to the Migrating from SAS® Software section in thisguide.


10

Getting Started

Workbench BasicsOverview

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 calledPerspectives and they contain different views, editors and control what appears in the menus and toolbars. A perspective can be changed by, for example, moving or removing views, resizing views and soon.

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 monthlyreporting 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 usingProjects), this is possible via the File Explorer View.

Views Displayed in the WPS Perspective

Project Explorer : Displays in a tree structure all the projects in your workspace. It allows you toopen files for editing and manages the programs and other files contained in a project. More aboutthe Project Explorer View.

File Explorer: Displays local and remote Host Connection file systems in a tree structure. You mayuse this instead of the Project Explorer to manage files if you wish. More about the File ExplorerView.

Editor and Output: Displays the contents of a program and allows you to edit it. It can alsodisplay the output generated by a program such as datasets, logs, HTML, etc. More about theEditor View.

Outline : Displays either the structure of a program (e.g. globals, DATA steps, procedures andmacros) or log (e.g. errors, warnings) that you have open in the Editor and Output view. Moreabout the Outline View.

Properties : Displays the details of objects like project folders, programs, libraries, datasets,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 Outputview. More about the Output Explorer View.


11

Results Explorer : Displays in a tree structure links to every ODS item generated to the variousdestinations (e.g. HTML or listing) from running a program. Each individual element can be clickedon to see that particular output in the associated Output view. More about the Results ExplorerView.

WPS Server Explorer : Displays in a tree structure the servers, libraries and their contents (e.g.datasets, libnames, etc.) that have been used by a program that has been run. More about theWPS Server Explorer View.

Link Explorer: Displays in a tree structure the Host Connections and local and remote WPSServers. More about the Link Explorer View.

Progress: Displays the name of the program that is currently being executed or the names ofprograms that are queued up, waiting to run. You can also use this view to stop a program runningor to remove queued up programs. More about the Progress View.

Console: Displays locally in the Workbench any console output generated by a remote WPSServer. 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 Helpmenu option. Note that once you have navigated away from the dynamic help page, the helpview will no longer dynamically update as you move around the user interface. However you canalways get context sensitive help on the current item by pressing F1, or by using the RelatedTopics link at the top of the Help view. More about the Help View.

WPS Link: WPS Link is the collective term for the technology used to provide a client/server facility. Itcomprises of Host Connections and WPS Servers. More about WPS Link.

WPS ComponentsObjects Managed by the Workbench

Projects: These are the fundamental unit of organisation for resources you wish to use in theWorkbench. Typically you would put related programs together in a project. For example, youmight have a project for applications under development, another for monthly reporting jobs, andso on.

Programs: You can create and edit programs using the WPS program editor. This editor usescolour coding to highlight different language elements as well as syntax errors. WPS recognises aprogram 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 logfile. This file can be viewed, printed and saved from within the Workbench. The log generatedby WPS is cumulative and contains the results of each program that has been run since WPSWorkbench was launched, the WPS Server was last restarted, or the log was last cleared.


12

Listing Output: This contains the printed output from any programs that you have run. Forexample, 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 outputgenerated by the WPS Server is cumulative and contains the output from each program that hasbeen run since WPS Workbench was launched, the WPS Server was last restarted, or the listingwas last cleared.

HTML Output: These are the physical HTML files that a program may generate. For example, theycould be a series of HTML files that show the results of analysing some data, and that have beengenerated as a result of an ODS HTML statement in a program. HTML output can be opened andviewed within the Workbench.

Managed ODS output: As described, the ODS (Output Delivery System) can be used to producetext listing and HTML output. Each program can specify when and where its output is stored but itis also possible to have the Workbench manage the process automatically. The default option isfor the Workbench to produce managed HTML output.

Libraries: These hold the temporary files, datasets, catalogs, etc that are created as a result ofrunning a program.

Datasets: The data generated from running a program is stored in datasets. You can view thecontents and properties of a dataset through various views within the Workbench.

Host Connection: A Host Connection defines a computer, local or remote, that Workbench hasaccess to.

WPS Server: The WPS Server is the engine responsible for executing programs and generatingthe resulting output, such as the log, listing output, HTML result files and datasets. A WPS Serveris associated with one Host Connection. The WPS Server also maintains an environment ofassigned libraries and filerefs, defined macros and macro variables and so on with which all of therunning programs interact.

Shortcut Directory: A Shortcut Directory defines a directory on a computer file system (local orremote), and is available in the File Explorer View for easy access to that directory and othersbelow it.

Cheat SheetsAbout

The Workbench is supplied with tutorials that are known as 'cheat sheets'. They are designed to helpyou get started with using WPS by introducing you to certain tasks and features. A cheat sheet is laidout as a sequence of steps that you undertake. As you progress from one step to the next, the cheatsheet has a help button that you can select to display a related help topic that discusses or guidesyou through that particular step.


13

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 anintroduction 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 largecomplicated topic, made up of lots of tasks, into smaller manageable groups. Each of these groups hasits own introduction and conclusion as below:

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


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:


15

1. From the main menu select Help ➤ Cheat Sheets....2. 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 aquick toolbar of buttons specifically for use with the cheat sheet. If you launch a cheat sheet from theWelcome 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 expandedstate. Click to toggle between these two states.

• Allows you to select and open another cheat sheet. If you already have a cheat sheet active, itscompletion status is automatically saved and then the new selected cheat sheet is opened. Onlyone 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 youlaunch a fresh cheat sheet, the Introduction step is expanded so that you can read a brief descriptionabout the selected cheat sheet.

For simple cheat sheets, to start working with the cheat sheet, select Click to Begin at the bottomof the Introduction step. The next step is expanded and highlighted. You should also see action buttonsat the bottom of the next step, such as Click to Complete. You can now progress through eachstep in the cheat sheet.

For composite cheat sheets, after reading the introduction you can start the first sheet by clicking theGoto to link at the bottom. You will then get the introduction for the first group of tasks, and you may

then click on the Start working link to begin. From this point on, the task group behaves very muchas a simple cheat sheet.

Progressing Through the Steps

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 groupyou are on. Composite cheat sheets have a conclusion, and also the option to 'Review' the task, or toprogress onto the next group of tasks (by clicking on the 'Go to' link). Starting the next task will put youin the introduction for the next group.


16

Getting Related Help Information

To get detailed instructions or related information for a particular step, select the Open RelatedHelp 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 marked as completed or not by simplyselecting its expand icon. Any step opened in this way will not change from its completed oruncompleted state. Also notice that steps after the active step do not have a Click to Completeicon. Click on the Collapse All Items but Current button at the top of the cheat sheet view tocollapse 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 thegroup in the task group pane. You will be placed back to wherever you were when you left that grouplast, so if you completed it, you will be able to see the conclusion. You may not, however, start anothertask 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) byclicking 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 yourestart 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 introductionfor 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 cheatsheet.

Composite cheat sheets are considered complete when all task groups are completed. If this is thecase, then all groups will have a check mark next to them in the groups pane. You may then restartall the task groups if you wish by right clicking the top level item in the groups pane and selectingRestart all tasks.

Closing the Cheat Sheet

You can close the active cheat sheet by selecting the Close icon in the cheat sheet's tab. Theactive cheat sheet saves its completion status when it is closed so that you can continue where you leftoff when you next re-open it.


17

Concepts

EclipseWPS 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 andmanaging files and tasks. It is designed to accommodate plug-ins to perform specific tasks, such asXML editing, Java Development, source control, etc. WPS Workbench is an example of the Eclipseenvironment supplied with a suite of plug-ins suitable for editing programs written in the language ofSAS and running them with the WPS Server (see WPS Server).

Because the Eclipse platform can accommodate other plug-ins, WPS Workbench has some featuresthat it does not presently utilise but they are included to allow users to add other Eclipse-based plug-insand extensions.

For more information about Eclipse and other available plug-ins, please visit the web site atwww.eclipse.org.

Eclipse Features Not Used by WPS

• Under the Project menu, none of the Build or Clean menu items are used by WPS.• The Help ➤ Check for Updates menu item will not retrieve updates for the WPS software. This

menu item will only retrieve updates to the Eclipse platform itself or other new or updated third-partyplug-ins.

WorkbenchThe term Workbench refers to the Integrated Development Environment (IDE). This environmentutilises the Eclipse platform as the basic framework to provide the Graphical User Interface (GUI). IDEand 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.

PerspectivesThe position of available views, windows, view stacks, menu items, and toolbar buttons displayed andthe 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 removingdifferent windows and views. The Workbench allows you to save customised perspectives and to switch

http://www.eclipse.org


18

between different perspectives. Refer to the Working with Perspectives section in this guide for moredetails about changing the layout of the Workbench.

All available perspectives, including any customised perspectives you save, can be opened from theWindow ➤ Open Perspective menu.

WPS Workbench is supplied with several different perspectives. Only the WPS perspective isdescribed in this section of the guide because it is the only one designed specifically for use withprograms.

WPS PerspectiveA WPS perspective is specifically intended for the task of creating, managing, editing and runningPrograms.

This perspective is the default used when you first install WPS Workbench. Its layout is depicted in thefigure below.

You cannot delete or rename the WPS perspective. However, you can save your own screen layoutunder the same name, thus replacing the original layout.

Noteworthy Features

By default, this perspective has the following features specifically for tasks concerned with managing orusing programs:


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 StackViews are organised in Perspectives by being members of a view stack. A view stack is a collection ofviews that are all allocated the same area in a perspective.

For example, the view stack below contains 2 views:

A view is opened in the view stack of which it was last a member. This is recorded in the perspective foreach 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, maximisingand restoring views.


20

ViewsThe layout of the items in WPS Workbench is known as a "perspective" (refer to Perspectives) andcomprises individual windows that contain one or more views. These views display specific typesof information and provide specific functions. Many views also have specific toolbars located in the topright of each view.

In the Working with Workbench Views section of this guide you can find out how to add, remove, resizeor dock individual views in any position on the Workbench.

Help ViewAs you select different views of the Workbench you can automatically display relevant help items in thecontext-sensitive Help view.

To Display this View

To add this view to the current perspective, select the menu item Window ➤ ShowView ➤ 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 seenumerous different controls available:

• Related Topics: If you follow any of the links in the Help view while it is docked inside theWorkbench, ensure you click on the Related Topics link (at the top of the Help view) to jumpback to the actual context-sensitive page. Otherwise the Help view will not automatically update asyou continue to use the Workbench.

• Show in External Window: This will open a Help window outside of the Workbench with acontents 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 inthe contents tree view of all available help topics.

• Bookmark Document: You can add a bookmark to any help page so you can navigateimmediately to that topic again. All your bookmarks are listed via the Bookmarks link in theHelp view.

• Search:Use this facility to search help for specific keywords.

Project Explorer ViewThe files and folders that can be edited and managed by the Workbench can be displayed in a treestructure in the Project Explorer view.


To add this view to the current perspective, select the menu item Window ➤ Show View ➤ ProjectExplorer.


21

The Files and Folders Displayed

The main file and folder objects that the Projects Explorer displays are:

• 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. Formore information about the Workbench tools available for manipulating projects please refer to theWorking with Projects section in this guide.

Working with Files and Folders

For more information about the Workbench tools available for manipulating the various objectsdisplayed in a project, please refer to the Project Explorer File Management section in this guide.

An Alternative

File system objects can also be managed using the File Explorer View. Refer to Working with FilesAnd Folders for help on choosing which view to use.

Operating System Tools

As well as the Workbench's tools, you can use your operating system facilities to delete, cut, copy andpaste objects into a project. You may need to use the Workbench's refresh tool to refresh the ProjectExplorer to ensure that objects manipulated in this way are displayed (right mouse click on the project and from the popup menu, select Refresh).

Note: If you do use the operating system tools instead of the Workbench tools, you will NOThave the added benefits that Local History provides.

Link Explorer ViewThe Link Explorer allows you to manage Host Connections you have configured, and also any WPSServers on these connections.


To add this view to the current perspective, select the menu item Window ➤ Show View ➤ LinkExplorer.


22

Objects Displayed

There are only two node types visible in this view:

• Connection node: The root node that represents a connection to a host machine. One ormore servers can be running on a connection. The connection can either be a local connectionor a connection to a remote machine. There can only be one local connection, but many remoteconnections.

• 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, youwill 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 mouseclick on an item and, from the popup menu, select the Properties option if it is enabled (i.e. thereare properties available for the selected item). Below are the items that this option works with, and thesort 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).• License Information: Full details about your licence 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: Auto-start, installation directory (for remote servers), startup environment variables (for local

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 dragand drop operation on a WPS server will move the server from its current Host Connection to thetarget 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 berenamed manually by right-clicking the server and selecting Rename from the context menu.


23

• Host connections can be imported by dragging Connection Definition Files (*.cdx) onto the LinkExplorer view. For further information on importing connections, see Importing Host ConnectionDefinitions from a File.

• Servers can be imported by dragging Server Definition Files (*.sdx) onto a Host Connectionnode in the Link Explorer View. For further information on importing servers, see Importing WPSServer Definitions from a File.

Properties ViewYou can display properties of various objects by using the Properties View. The properties thatappear in this view dynamically change depending on the item that is currently selected.


To add this view to the current perspective, select the menu item Window ➤ Show View ➤ Properties.

Views that Interact with the Properties View

If you click on an object in one of the views listed below, you will see the appropriate properties for thatobject 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 server version, and the following information about a License:• Expiry Date• Grace Period• Licensed Operating System• License Number

Outline ViewTo assist in navigating programs, logs, listing or HTML output the Workbench displays structuralelements contained in these files in the Outline view. If you click on a structural element in this view,the relevant line in the file will be highlighted.

Opening or giving focus to a program, log, listing or HTML result file will make the Outline viewautomatically refresh to display the structural elements that are relevant to the file that has focus.


To add this view to the current perspective, select the menu item Window ➤ ShowView ➤ Other… ➤ General ➤ Outline.


24

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 quicktoolbar at the top of this view you will see icons with a diagonal line through them representingstructural elements. These buttons can be used to toggle off and on the relevant structural elements inthe 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 structuralelements:

• Results parent node• HTML tabular output• Listing Tabular output

Output Explorer ViewThe output files generated from running a program, are listed by, and can be opened from, the Output Explorer view.

Note: To view hierarchical lists of results, grouped by server, please use the Results ExplorerView.

While the Workbench is open, the output from previous runs is not automatically deleted. In order toclear previous output, you can use the WPS ➤ Clear Log or WPS ➤ Clear Results or therelevant toolbar buttons or context menus.

Alternatively you can use the Restart Server feature.


To add this view to the current perspective, select the menu item Window ➤ Show View ➤ OutputExplorer.


25

Output

Output items are associated with, and listed underneath the server on which they were generated. Thefollowing output items is always shown under each server whether any programs have been run yet ornot:

• Log output

The following output items may be shown under a server if that server has run programs that havegenerated 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 outputnodes 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 WPSServer. 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 WPSServer in its relevant editor. If the output type is anything other than log output then at the sametime as the output is opened in the editor, you will also see the individual result elements listed in theResults 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 Workingwith Program Output.

Results Explorer ViewThis 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 add this view to the current perspective, select the menu item Window ➤ Show View ➤ ResultsExplorer.

Output

Once a program is run an entry will appear under the relevant server for every PROC that producedoutput. For example PROC PRINT will produce an entry named "The print procedure." Expand this linkto find links to each type of output specified. Output types can be:• WPS managed HTML output

• WPS managed Listing output

• Manually managed HTML output


26

• 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


For details about listing and opening datasets, please refer to Working with Program Output.

File Explorer ViewThe files and folders that can be edited and managed by the Workbench are displayed in a treestructure in the File Explorer view.


To add this view to the current perspective, select the menu item Window ➤ Show View ➤ FileExplorer.

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 localor 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, whereavailable.

Note: The File Explorer only displays connections that are open.

Working with Connections and Shortcuts

It is only possible to view files on remote systems when you have an open Host Connection. HostConnections can be opened from Link Explorer View, and connections are also opened when startingWPS Servers in the WPS Server Explorer View.

Each Host Connection is configured to have one or more Shortcut Directories, that permit access to thefiles and folders on the file system.


27

When a Host Connection is opened, then the Connection will appear in the File Explorer View.Closing a connection will remove its node from the File Explorer View.

Host Connections expand into Shortcut Directories in the File Explorer View. Shortcut Directoriesthat are invalid are shown with an Invalid Shortcut icon. This means that the path configured forthese shortcuts is not available on the file system for that connection.

Properties

Selecting an item in the File Explorer View shows 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.• 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 mainmenu.


28

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 withthe 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 movingthe mouse cursor to the Run On menu option in the context menu. The menu will then expand toshow the list of servers the program can be run on. Choosing a server will then run the program on thatserver.

For more information on running programs please see the following sections of this guide:

Running a Program

An alternative

File system objects can also be managed using the Project Explorer View. Refer to Working withFiles And Folders for help on choosing which view to use.

WPS Server Explorer ViewAll file references, libraries, catalogs and datasets that have been generated as a result of running aprogram 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 add this view to the current perspective, select the menu item Window ➤ Show View ➤ WPSServer 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 runningyour programs. This is probably a Local installation of WPS.

• Libraries: A parent node for individual library items.• Library: A collection of catalogs and/or datasets.• Catalog: A collection of user defined items such as formats and informats.• Dataset: A data file containing numeric and/or character fields.• Dataset View: A dataset that is created by executing a view in the source data.• Numeric Dataset Field: A dataset field that contains numeric values.


29

• Character Dataset Field: A dataset 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 ifone is not specified in a program. If you use the LIBNAME statement in a program to specify your ownlibrary name, then you will see a library node with the specified name listed in the WPS Server Explorerview.


For details about listing and opening datasets, 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 WPSServer 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. Rightmouse 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 andthe 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 Read-only 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.

Dataset and Dataset View Properties• General: The field count and number of observations.• Columns: A table of information about the dataset fields including name, type, length, label, format

and informat.


30

Editor ViewWhen 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 theWindow ➤ 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. Thisis 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) itdepending 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 dataset 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 ViewWhen you are Running a Program, it is listed as executing in the Progress view. Also, operationsperformed in the File Explorer View are also visible here (both operations that are in progress, andthose that are complete).

While a program is executing, and during File Explorer operations, there is also a progress indicatordisplayed in the lower right hand corner of the Workbench. This indicator is displayed regardless ofwhether you have the Progress View open or not.


To add this view to the current perspective, select the menu item Window ➤ Show View ➤ Progress.

File Explorer Operations

An operation performed from the File Explorer View will remain in the progress view until anotheroperation is performed. This allows you to see the results of the operation, if desired.

Clicking on the Completed link will reveal the File System Operation Dialog, showing you more detailedinformation about the operation.

Working with the Progress View

For more details about working with the program's Progress View, please refer to the following sectionsin this guide:

• Stopping a Run


31

• File System Operation

Bookmarks ViewYou can add Bookmarks on any line inside a program, or indeed inside any file that you canopen and edit with the Workbench via the Project Explorer View. To list and navigate between yourbookmarks, 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.

Note: It is not possible to create bookmarks on files opened from the File Explorer View, unlessthey are members of a project . This is because files opened outside of Projects may beanywhere in the filesystem, and bookmarks can only be set on files that are members of aworkspace project.


To add this view to the current perspective, select the menu item Window ➤ Show View ➤ Bookmarks.

Tasks ViewYou can add Tasks (reminders) against any line in a program that has been opened from the ProjectExplorer View, and associate them with notes and a priority level. To list, update and navigate betweenany 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 notlist those from programs in a closed project.

Note: It is not possible to create tasks on programs opened from the File Explorer View, unlessthey are members of a project. This is because programs opened this way may be anywherein the filesystem and tasks can only be set on files that are members of a workspace project.


To add this view to the current perspective, select the menu item Window ➤ ShowView ➤ Other… ➤ General ➤ Tasks.

Search ViewThe results of performing a search are displayed in the Search view. You can use this view to openthe file right where the item appears.


To add this view to the current perspective, select the menu item Window ➤ ShowView ➤ Other… ➤ General ➤ Search.


32

Types of Search

The main menu option Search ➤ Search is a flexible tool that provides a wide variety offunctionality:

• Search for a text string contained in any file in any open project in the Workbench. You can usewild 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.

Console ViewThe Console view is not currently used if you are only running programs on a local server. In thissituation it will remain blank.

It can, however be extremely useful if you are running your programs on a remote WPS Server. In thisscenario, 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 programon the remote server which might be requesting a listing of the contents of a particular directory. Inthis case the output from running the X statement will be displayed in the Console view. It is alsoextremely valuable when a remote server fails to start, or terminates abnormally. In this situation errortext is typically displayed in the Console view.


To add this view to the current perspective, select the menu item Window ➤ ShowView ➤ Other… ➤ General ➤ Console.

ProjectsAs far as the Workbench is concerned, a project is a parent folder that contains other objects suchas 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 numberof 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 Projectssection of this guide.

All projects belong in a Workspace. You can only work with one workspace at a time within theWorkbench but you can switch between different ones as desired. The Project Explorer View is usedto display and manage the current workspace and the projects it contains.


33

Project Definition FileIn the root directory of a project is a project definition file called .project. This file contains informationabout 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 outsideof 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

Working with Multiple ProjectsMore than one project can be open at any one time in the Workbench. There are many ways to endup 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 aboutusing these facilities in the Workbench, please refer to the Working with Files And Folders sectionin this guide.

WPS LinkWPS Link is the collective term for the technology used to provide a client/server facility. Using theWPS Workbench GUI on your local PC (the client) you can connect to a networked computer (theserver) to manage and run programs on that remote server. WPS Link involves using concepts we referto as Host Connection and WPS Server.

Host ConnectionHost connections allow users to access computers, either for running programs (via a WPS Server) orfor managing files and folders.

Local Host Connections are available if the local WPS Server component is installed. This allows youto have one or more local servers for running programs written in the language of SAS. The ability tohave multiple WPS Server nodes can be a useful way to setup different options or locale settings to usewhen running your programs.

Remote Host Connections allow you to connect to remote computers. They have additional propertiesthat 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 Serverand cannot be run on a Host Connection alone.


34

Management of files and folders on remote systems is possible via the File Explorer View.

WPS ServerIn order to run a program (see Running a Program), the Workbench requires a connection to a WPSServer. The term Server here is used to refer to a server process. The process may be running on thelocal workstation machine (a local Host Connection), or may be running on an installation of WPS ona remote machine (a remote Host Connection). Servers running under the local connection are termedLocal 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' anda server called 'Local Server'. This server will be started by default when the Workbench is started.Further local servers can be created if required (see Creating a New Local WPS Server) or the localserver can be deleted. Deleting all local servers, where there are no remote servers, will render usersunable to run programs.

Creating multiple local servers requires no further licensed WPS products and the only restriction on thenumber of local servers that can be created is the local machine resources. One reason that you mightwant to create multiple local server connections is to configure them with different startup options, forexample different values of LOCALE or ENCODING.

The term Remote Server refers to a WPS Server running under a Host Connection on a remotemachine. Such a setup will require a licensed WPS Server installation on the remote machine. Settingup remote server connections gives the user the ease of use of the Workbench at their local workstationwhile giving them access to the processing power of a remote server machine. Multiple servers can rununder a single remote Host Connection. Once a connection to a remote machine is authenticated, oneor more WPS Servers can be started without the need for further user authentication. Multiple users canhave remote connections configured to the same machine, with the only restriction being the resourceson that machine. Remote connections can be created by following the steps in Creating a New RemoteWPS Server.

The list of servers that are defined is stored within the Workspace, so changing your workspace willload a new list of servers, which may differ. It is not possible to edit this list directly, but it can bemaintained 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 aFile).

The WPS Server Explorer View and Link Explorer View will show the list of servers (Server Explorer) orconnections and servers (Link Explorer) that are currently defined in the Workbench. Through the LinkExplorer View you can define new connections, new servers, edit their properties, delete connectionsand servers and export and import connections and servers.


35

The Default WPS Server

One of the defined servers is always set as the default server. There will only be one default server forall connections. This server is shown in bold in the WPS Server Explorer View and the Link ExplorerView.

The default server is the one that is acted upon by default when, for example, you run a program usingthe 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 workstationinstallation of WPS Workbench will come with a single local server configured that is launched when theWorkbench 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 assignedduring the execution of a program, they are available to other programs that are run during the sameWorkbench session.

Log output is cumulative and shows information and any errors from each program that has been runduring the current session. It can be cleared using the Clear the Log option.

Listing output, like log output, is cumulative and shows the results of every program run in the currentsession. HTML output similarly shows the results of programs but is not cumulative. Listing and HTMLoutput can be cleared using the Clearing the Results Output option.

The server itself can also be restarted, using the Restart Server option. This will clear the log aswell 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 Output Explorer View will display all the log, listing output and HTML result files that have beengenerated.

The Results Explorer View will display a hierarchical list of listing and HTML output.

The WPS Server Explorer View will display all the libraries, datasets and file references that arebeing maintained in the WPS Server environment.

WorkspaceThe term Workspace refers to the container that holds your Projects. It is possible to use any folder onany drive that your computer can access as a workspace.

The workspace must have a physical location. However, projects within a workspace can, but do notnecessarily have to reside beneath the parent workspace folder.


36

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 $HOMEenvironment 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 tochange the workspace location.

ProgramsA program is a program written in the language of SAS.

You can create and edit programs in the Workbench using the SAS Editor. This editor uses colourcoding to highlight errors and to help distinguish the various keywords, variables, values etc that makeup a program.

To assist navigation the Workbench displays the structural elements of a program in the OutlineView.

Quick Difference Indicators

As you modify a program, quick difference indicators automatically appear in the left hand white borderof 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 colouredindicator in the left hand border it will display the section of code as it was before you made thechange.

• 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 NextAnnotation and Previous Annotation controls.

Program NamesA program can have any name you desire (subject to your operating system's restrictions) but itmust have a file extension of .wps or .sas. Files with either of these extensions are handled the sameway 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 youcan type in any name you desire. If you do not specify an extension the program will automatically becreated with the extension .sas.


37

Working with Multiple ProgramsYou can have as many projects open in your Workbench as you like and each of these projects cancontain 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 tab is displayed in the top of the Editor window. Anopen program can be given focus in the editor window by clicking on its tab.

Program Colours and LayoutColours used to display language elements in a program and various other display elements haveWorkbench 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 SyntaxColoring preferences.

Program Layout

The layout of a program, whether to display line numbers, and indeed a whole number of other displaycontrols can all be user defined. Refer to the General Text Editors section for more details.

Program Writing and EditingAlthough it is possible to open a program with various editors provided with the Workbench, only theSAS 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 asa PDF file and also can be accessed from the Workbench menu Help ➤ Help Contents ➤ andthen selecting Wps Reference for Language Elements from the left hand contents menu of theHelp 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 get WPS to prompt you with suggestions when writing aparticular 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 languageitems.

The white border is also used to display quick difference indicators.


38

Quick difference indicators are useful for showing you what edits you have made recently to a given lineof a program. When you change a line of code a quick difference indicator will appear as a colouredblock in the left hand side of the white border to the left of the program editor. If you hover the mouseover this coloured block a popup window will show you what the code looked like before you changedit.

Annotations

An annotation is a marker displayed in the left hand grey border of a program that is open in the Editorview. The annotations that you may see displayed are:

• Bookmarks• Tasks• Search results

You navigate between annotations in an individual program by using the Next Annotation and Previous Annotation controls.

Local HistoryThe Workbench maintains a local history of modifications to programs or other files manipulated inthe Workbench when using the Project Explorer View.

Even when you close the Workbench and re-open it the local history is preserved. Copying a programalso 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 tothe Workbench's local history. If you modify a file outside of the Workbench, or modify a file openedwith File Explorer, there will be no record added to the history. This history provides the ability to takeany of your current programs and Compare with Local History, or even to Replace with Local Historyto take the file back to a previous edited version. Each modification in the local history is uniquelyrepresented 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 theProject 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 theitem 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 inthe history and the maximum file size that can be recorded.


39

Running a ProgramYou can run a program either from inside the Workbench or from a command line outside of theWorkbench.

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 programis running and you attempt to run another one on the same server, that program will be queued and willnot execute until the other program has completed. You may, however, register more than one WPSServer, 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.

While the Workbench is open, the output from previous runs is not automatically deleted. In order toclear 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 previousoutput and completely clear the state of a WPS Server, including emptying the WORK library anddeassigning 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, unlessthe 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 acommand 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 aprogram, please refer to Working with Program Output.

For details about various preferences that can be specified regarding running programs, please refer toWPS .

Managing ODS OutputOnce you have run a program that produces some output using ODS you can view the results in theResults Explorer View. The ODS Destinations to which WPS outputs, and the location of the outputgenerated, can either be managed by yourself with explicit ODS statements in your code, or you canleave the Workbench to manage the results automatically.

The choice as to how you want the Workbench to manage ODS output for you really depends onwhether you require complete control of all your output and its location or not. For example, if, in thelong term, the program you are running in the Workbench will be run in a batch environment (depending


40

on your environment see Run a Program on the Command Line in Windows or Run a Program on theCommand Line in a Non-Windows Operating System) then the program itself will have to control theODS Destinations and the locations to which it writes. If it does not, it will not function correctly withinthe 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 moreinterested in seeing the results presented in the Workbench, rather than being concerned with wherethey are written, then automatic management will be a useful feature for you.

By default WPS controls results automatically, and sets the default ODS Destination toHTML. This setting can be changed by modifying the Result Option preference accessible viaWindow ➤ Preferences ➤ WPS ➤ Result Options. Please see WPS Result Options for details aboutthe settings available for this preference.

LibrariesA library is used to store WPS data files, including datasets. On the majority of operating systems, itmaps directly to an operating system folder. The operating system folder may contain non-WPS files,but only the files with extensions that WPS recognises will be visible in the Workbench.

A library allows you to organise collections of data in a logical way. You can direct the output of a WPSprogram to a specific library, and perhaps to read other data from a shared library.

Libraries may be read-only, so that you are unable to change their contents (the default librarySASHELP is one such library).

The WORK library is automatically cleared of all data when your WPS session ends. Any data youwish to keep at the end of the session you will need to write to your own permanent library, or to theSASUSER library.

DatasetsA dataset is a file created by a WPS server, and stored in a library. It contains rows and columns, verymuch like a database table. These rows and columns are known as observations and variables inWPS.

Observations (rows) usually relate to one specific entity (for example, an order or person).

Variables (columns) describe attributes of an entity (for example, an item id in an order).

Table 1. Example Dataset

Order ID Item ID Quantity Unit Price

10001 47853 3 30.75

10001 23104 10 4.90


41

Order ID Item ID Quantity Unit Price

10002 62091 1 89.99

In the above example, each observation is an item in an order. The variables are Order ID, Item ID,Quantity and Unit Price.

Analyser ToolsThe Workbench has tools that can scan existing programs written in the language of SAS. These willgenerate reports that can help to indicate which of your existing programs written in the language ofSAS will run unchanged in WPS, which programs may need some modification, and which programscontain 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 multiplefolders (via File Explorer View) containing hundreds of programs. Even when analysing hundreds ofprograms, an analysis report is often generated in less than a few minutes without the need to actuallyrun the programs or connect to any data sources.

Analyse Program Compatibility : To determine if your existing programs or projects contain anyunsupported language elements.

Analyse Language Usage : To list every single language element that has been used in selectedprograms or projects. The analysis will indicate which elements are supported and which areunsupported.

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 analysisreport 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 elementsused in programs. It does not report any supported language elements that were used in theprogram(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 SASthat are used in programs, i.e. both supported and unsupported elements.

This style of report is generated when you Analyse Language Usage .


42

Related Topics:

• Analysis Restrictions• Opening Analysis Reports• Navigating Analysis Reports• Export Analysis Results to Excel

MarkersMarkers are objects that can be associated with any program. The two types of marker in theWorkbench are:

• Bookmarks• Tasks

These markers are listed in their respective marker view and also in the left hand margin or gutter of anopen program.

BookmarksA bookmark is an anchor that you can specify so that you can quickly navigate back to that point atany time in the future.

Note: It is not possible to create bookmarks on files opened from the File Explorer View, unlessthey are members of a project . This is because files opened outside of Projects may beanywhere in the filesystem, and bookmarks can only be set on files that are members of aworkspace project.

There is no limit to the number of bookmarks that you can create. Using the Edit ➤ Add Bookmarkmenu option, you can either add a bookmark on a particular line within a program, or against anindividual program file listed in the Project Explorer View . For lines within a file you can also use thecontext menu Add Bookmark... from the gutter.

You can then list and navigate between all your bookmarks via the Bookmarks View ( Window ➤ ShowView ➤ 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, navigateand manage bookmarks.

TasksA 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 levelof high, normal or low. There is no limit to the number of task markers you can add inside a program.


43

Note: It is not possible to create tasks on programs opened from the File Explorer View, unlessthey are members of a project. This is because programs opened this way may be anywherein the filesystem and tasks can only be set on files that are members of a workspace project.

You can then list and navigate between all your tasks via the Tasks View ( Window ➤ Show View ➤ Tasks ).

The Tasks view also allows you to change priority levels, edit the description and either tick or un-tick the task.

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 andmanage task marks.

Context-Sensitive HelpIf you encounter a view you do not understand, use the context-sensitive help (ensure the view inquestion has focus by clicking on it and then press F1 on your keyboard). The Help view will display ashort description about the view and list related topics. Leave the Help view open to see information onother 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 automaticallyupdate 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 aboutlanguage elements. Either add a new language element to a program or point to an already writtenelement and the Help view will update to show related topics.

DialogsDialogs are used in the Workbench to show information or gather user input.

File System OperationFile 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 willallow you to display the File System Operation Dialog, to see more detailed information about the mostrecent operation.

Information shown includes:


44

• Status : Success or Error• Operation : Copy, rename, delete etc.• Source : Original location of the file or folder• 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 ofthe operation. For example, if you attempt to delete 5 files and the first one fails, it will still attemptto 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


45

Tasks

Working with Workbench ViewsYou can manipulate the individual Windows and Views of the Workbench to create your owncustomized Perspectives.

This section of the guide describes how to manipulate the individual views.

Closing a ViewTo 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 ViewYou 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 resizeicon.

2. Press your left mouse button and keep it pressed while you drag the border to make it larger orsmaller.

3. Release the mouse button to complete the resize operation.

Moving a ViewYou will need to understand the View Stack concept before reading this topic.

To Start Moving an Individual View or Editor:

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 anew view stack in that location.

• You can add the view to an existing view stack, and its tab will appear alongside the other views inthat 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.


46

2. The view stack will divide. This represents how the Workbench will arrange the existing viewstack 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 reducein 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, indicatingwhere 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 ViewYou can detach from the Workbench window any individual view into its own window.

To Detach a View:

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 mainWorkbench 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 theWorkbench.

Note: If you close a detached view, it will still be detached when you next open it.

Minimise a WindowYou 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 inthese views appearing as buttons with icons on either the left or right of the Workbench, as seen here:


47

To minimise a window or view:• Click on the Minimise button of the relevant window or view

Maximise a WindowTo 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, otherviews that occupy the same view stack (designated by the adjacent view tabs) are also maximised, butthe original view remains on top, and still has focus. All other view stacks will be minimised to the edgesof the Workbench window represented as icons.

Restore a WindowYou 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 ViewStack, occupying part of the Workbench Perspective. Views that have either been maximised orminimised can be restored. Minimised views appear as buttons to the left and right extremes of theWorkbench 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.

Opening a ViewTo open a view in the Workbench:


48

1. Select the menu option Window ➤ Show View.2. If the required view is not immediately listed, then select Other... from the drop-down menu to see a

complete list of views.You will be presented with a list of all the available views grouped under category folders.

3. Highlight the view 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. Itsopening position in the Workbench will be the same as it was when it was last closed.

Working with PerspectivesYou can customise any of the supplied Perspectives and save them to create your own. You canalso swap between any saved perspectives while you are working.

To get the most out of customising a perspective, you should also read the section in this guideconcerned with Working with Workbench Views to learn how to change the layout and position ofindividual views and windows within a perspective.

This section of the guide describes the various ways you can manipulate perspectives.

Resetting a PerspectiveAt 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 PerspectiveIf you have changed the layout of a perspective, you can save it under a user defined name for futureuse:

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 wantto 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 PerspectiveTo 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.


49

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 aperspective that was supplied with WPS.

Opening a PerspectiveTo open a different perspective:

1. Select the menu option Window ➤ Open Perspective.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 (bydefault) of the Workbench. If you have other perspectives open at the same time, they will be listed inthis area also so you can click on them quickly to change between them.

Closing a PerspectiveTo 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 youwish to close by clicking on its quick button (the default position of open perspective quick buttons isnear the top right).

2. From the main menu select the option Window ➤ Close Perspective.

Switching Between Open PerspectivesIf 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 listis near the upper right of the Workbench. They are listed with their individual icon and name to theright of the Open Perspective icon.

2. Click on one of the perspectives listed. The Workbench will switch to that perspective.

Work the Way You WantWPS will remember when you next open the Workbench, exactly how the windows and views werearranged, etc, when you last closed it. You do not even have to save a perspective to ensure that thishappens.

This ensures that your favourite perspective is immediately available for you as soon as you openthe Workbench.


50

Working with ProjectsThe 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, ifyou wish. See the File Explorer File Management topic for more information on this.

Creating a New ProjectTo create a new project:

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 ➤ Project Explorer).

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.

If the name of the new project is not an existing folder, a new folder will be created. If a folder withthe 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 defaultcheckbox and specify the new Directory.

Caution: If you choose a directory outside of the current active Workspace, then be aware thatby 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 ProjectYou can use the Workbench's Copy and Paste facility to create a new project based on anexisting project.

For general information about this facility, please refer to the Copying Objects section in this guide.

Deleting a ProjectTo delete a project:

1. Ensure you have the Project Explorer view open ( Window ➤ Show View ➤ ProjectExplorer).

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 willpermanently remove the project folder and its contents from the file system.


51

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 projectin the Workbench.

4. Click the Yes button to proceed with the delete.

Closing and Opening a ProjectWhen you have multiple open projects in the Workbench, you might like to close some projectsto make sure you don't accidentally manipulate the wrong programs.

To Close a Project:

1. Ensure you have the Project Explorer view open ( Window ➤ 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, anyprograms 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 ➤ Project Explorer).2. Highlight the closed project3. select from the main menu Project ➤ Open Project.

Exporting a ProjectTo make a copy or backup of a project and all the files and folders it contains:


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 asWinZip.

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 forexporting along with all the objects it contains. If you want to change your selection, you could clickthe Deselect All button to make sure nothing is selected and then in the left hand window, tickthe 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.


52

8. In the To Directory, use the Browse… button to select the location where you want to place theexport.

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 youlook at the target location you chose in Step 8, you can either see a zip file, or all the copied files andfolders.

Importing Files or Archive FilesTo import files from either an archive file (such as a zip file) or from the file system:

1. You need to import into an existing project. If you do not have an existing project you need to refer tothe Creating a New Project section.

2. To start the import process, select the main menu item File ➤ Import…. The Import window willopen.

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 ortar.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 filesyou want to import.

7. When you have set the From directory or From archive file, you should see a list of the files andfolders 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 willend up with your imported files inside a sub-folder in your new project.

Restriction: Do not import a project definition file ( .project ), otherwise it will overwrite theone 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.

Importing an Existing ProjectTo 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:


53

• Select root directory: Use this if the project is not archived in a single file. (zip, tar or tar.gz, forexample). 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 Projectssection of this panel.

6. Click the Finish button to start the import process.

Switching to a Different WorkspaceTo switch to a different Workspace so you can display or create a different group of projects:

1. So that you can see the outcome of switching Workspaces, first ensure you have the ProjectExplorer View open ( Window ➤ Show View ➤ Project Explorer).

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.• 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 ProjectsThis section of the guide is aimed specifically at users who have existing Projects or Programscreated using either software from SAS Institute Inc. or earlier versions of WPS and want to use theseexisting 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 manageyour Workbench resources. Using the File Explorer View, any file accessible through theoperating system is now available from within the Workbench. You can also make connections toother computers to use programs stored elsewhere.


54

Migrating from Previous Versions of WPS

Introduction

Workspaces opened with previous versions of WPS can be opened with the current version, so thereare no migration steps to be performed to use a Workspace from a previous version of WPS with thelatest version.

Furthermore, any existing programs do not need to be modified to work with the latest version ofWPS. Typically Projects created with earlier versions of WPS can be opened and used by later versionsof 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 usethese programs with WPS. Any file with the extension .sas is assumed to be a program that theWorkbench can open, edit and run.

Accessing your existing programs

You can access your existing programs from the File Explorer View. Through this view, it is possibleto access any program you have on your local operating system, and you can also connect to othercomputers to access programs.

Alternatively, you may wish to work with Projects in the Workbench. Working with projects through theProject 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 thisguide.

Check Program Compatibility

Before trying to execute your existing programs in WPS it is recommended that you first use theWorkbench Analyser Tools to determine if your existing programs in the language of SAS contain anylanguage 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 tocomplete and can therefore be quicker than trying to execute long-running programs only to find thatsome changes may be required. Program analysis is available from both File Explorer View and ProjectExplorer View.

It is also worth pointing out that simply opening Programs in the Workbench will also display unknownor unsupported language elements in red.

Note that, although they are generally very accurate, the Analyser Tools are not guaranteed to be100% accurate due to the nature of the syntax of the language of SAS making this difficult to achieve.


55

Using your Programs in the Workbench

For more details on how to use your programs in the Workbench, please refer to the Working withPrograms section in this guide.

Working with Files And FoldersIn this section of the guide we will look a little closer at how you can manipulate the various objects thatare contained in the projects and in the file system.

The Project Explorer View is ideal where you have a set of files you need to manage from oneorganised local repository (called a Workspace). You can create one or more Projects in aWorkspace to tackle specific tasks. Any kind of local file can be contained in a Workspace, and alloperations you would expect to be able to perform on files are available (including the ability to runprograms). Workspace objects can be managed with Local History, and they can also be exported toarchives or to other folders in the local file system, and such archives may also be imported in this view.

The File Explorer View differs from Project Explorer in that it permits access to all files availableto you on your local file system, and also to remote file systems, via Shortcut Directories. ShortcutDirectories are similar to Projects and point to folders at any level within the file system on which theyare 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 2. View Options Summary

Option Project Explorer File Explorer

Open and Edit Yes Yes

File Management Yes Yes

Run Programs Yes Yes

Local History Yes No

Import and Export Projects and Archives Yes No

Manage Remote File Systems No Yes

Manage Full Local File System No Yes

Project Explorer File ManagementThe 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.


56

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. .wpsor .sas are treated as a program, .doc is regarded as a Microsoft Word document) then the newfile will be associated with the appropriate editor. If no file extension is specified or the extension isnot one that the system recognises, the default action is to associate the new object with the WPSWorkbench 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 filein the Editor, move the mouse over the tab and then selecting the close button that appears to theright of the name.

To find out the different ways you can open a file, you should read the Working with Editors section inthis guide.

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 workspaceand no folder will be created in the file system. You can create links to other files and folderswithin this new folder, and also add other virtual folders. To do this, simply drag and drop yourother project resources into the virtual folder. It is not possible to create physical files and folderswithin virtual folders.You can use this option to organise an alternative view of files and foldersindependent of their physical location.

• Link to alternate location (Linked Folder). When you link a folder to an alternate location, thefolder represents the contents of this folder in the alternate location directly. Any changes youmake to the contents will affect the folder in the file system. The Workbench will record anychanges to files that you make with the Workbench, allowing the use of local history with thesefiles (see Working with Local History). Use the Browse... button to choose a folder in your filesystem to link to.


Moving an Object

To move any object from one project to another:

1. Ensure you have the Project Explorer view open (Window ➤ Show View ➤ ProjectExplorer).


57

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:


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.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 a whole project is discussed in Deleting a Project. The behaviour of objects when beingdeleted in that way is slightly different from that discussed below.

To delete an individual object from a project:


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 OperatingSystem 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 Explorerwill not be able to use features such as local history. These features rely on files belonging to aProject. Such Project files are known as "resources" within the Workbench.

Renaming an Object

To rename an object, or even the project itself:


2. Click on the object you wish to rename.


58

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 ManagementIn this section of the guide we will look a little closer at how you can manipulate the various objects thatare 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 wellas 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 beable 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 FileManagement).

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 ➤ File Explorer).

2. Right-click the container object ( Shortcut Directory or Folder) you want to create the new filein, 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 willsee that the container from where you opened the context menu is currently selected. You maychoose 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. .wpsor .sas are treated as a program, .doc is regarded as a Microsoft Word document) then the new filewill be associated with the appropriate editor.


Creating a New Folder

Folders can be created where you have appropriate operation system privileges on your local andremote connections.



59

2. Right-click the container object ( Shortcut Directory or Folder) you want to create the newfolder 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. Youmay choose to create the folder on an entirely different connection, if you wish, even a remoteconnection.

5. Near the bottom of the window, type in the new Folder name.6. Press the Finish button to complete the task.

Copying Objects

You can copy file system objects to folders in your local connection and remote connections. There areseveral ways to do this, and two of these are explained here.

Copying Objects using the Menu

You can copy file system objects to folders in your local connection and remote connections:


2. Either right click on the object you want to copy and select Copy, or select it and use the keyboardshortcut for copy for your operating system.

3. Right click the target Shortcut Directory or Folder you want to copy the object to, and clickPaste, or select the target and use the keyboard shortcut for the paste operation for your operatingsystem.

The progress of the operation can be viewed in the Progress View.

Tip: You can also select multiple objects if you wish to copy more than one object at once.

Copying Objects using 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 ➤ 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 Folder object and release the mouse button, then the key, to perform the copy tothat location.


Tip: You can also select multiple objects if you wish to copy more than one object at once.


60

Moving an Object

You can move file system objects to folders in your local connection and remote connections. Thereare several ways to do this, and two of these are explained here.

Moving Objects using the Menu

You can move File Explorer objects by using the options on the Edit or right-click menu, or by using thekeyboard shortcuts for your operating system.

1. Ensure that you have the File Explorer view open (Window ➤ Show View ➤ File Explorer).

2. Select the object that you want to move and select Cut, or else use the keyboard shortcut for Cut foryour operating system.

3. Select the target Shortcut Directory or Folder to which you want to move the object andselect Paste, or else use the keyboard shortcut for Paste for your operating system.


Tip: You can also select multiple objects if you wish to move more than one object at once.

Moving Objects using Drag and Drop

You can drag and drop files and folders to move them.


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 a visible Shortcut Directory or Folder, to

move the object to that location.


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 menu3. From the menu select the option Delete.4. Click OK to confirm you wish to proceed with the delete.


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 .


61

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.5. Press Enter on your keyboard when you have finished typing.

Progress of the operation can be viewed in the Progress View.

Working with EditorsIn any of the Perspectives supplied with the Workbench or that you have created, there is always anEditor View. In this section of the guide we will look a little closer at the various ways of opening fileswith different editors into this view.

You can open programs from either the Project Explorer View or the File Explorer View. The ProjectExplorer offers more control than the File Explorer, which determines the most suitable editorautomatically, based on the filename extension of the file you are opening.

Opening files with Project ExplorerWhen using the Project Explorer View, you have control over exactly how the Workbench should openyour files. The different methods are explained here.

SAS Editor

The SAS Editor provides features suitable for editing programs (programs written in the language ofSAS), such as colour coding of the language elements. Only files with an extension .wps or .sas can beopened in this editor.

Programs may either be opened from a Project, or directly from the filesystem. Programs opened froma Project allow additional Workbench features to be accessed including local history. However usingprojects 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 ➤ Project Explorer).

2. Right mouse click on the program you wish to open.3. From the popup menu select Open With ➤ SAS Editor.


62

4. If your program does not belong to a project you can drag a file into the Workbench from theoperating system file system explorer, or other external tool. You can also use the File ➤ OpenFile... menu option.

Text Editor

The Workbench has a basic 'text' editor. You can open a program with this editor but the contents willbe treated as regular text, i.e., no features are available in this editor for colour coding.

To open a file in the Text Editor:


2. Right mouse click on the file you wish to open.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 beregistered to Microsoft Word), then the System Editor will launch that application with the file in a newwindow outside the Workbench.

To open a file with the System Editor:


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 documentin your project and use the In-Place editor, the Word document will open in the Workbench's Editorwindow 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 useseither the application associated with that file type, or the editor last used to open the file.

To open a file with the Default Editor:


63


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 files with File ExplorerOpening files with File Explorer is straightforward, because the Workbench will decide which is the mostappropriate editor to open it with.

1. Ensure that you have the File Explorer View open.

2. Find the file you want to open, and double click it.

The file is opened according to the extension:• Program files (.wps and .sas file extensions) are opened in the SAS Editor.• Text files (.txt) are opened in the Text Editor.• XML files (.xml) are opened in the Text Editor.• HTML files (.html) 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 applicationassociated with the file, even if it cannot be opened in the Workbench itself.

Working with ProgramsThis section of the guide describes the tools associated with editing and running Programs and theoutput they generate.

Creating a New ProgramTo 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 calledProgram 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.


64

Note: This step creates a new shortcut to the existing program. You will not physically have anew program in your project.


You will see the new program appear in the Project Explorer view and it will automatically openin the Editor window ready for you to start typing in code.

Opening a Program that is outside of a ProjectNote: Ensure you have the File Explorer view open ( Window ➤ Show View ➤ FileExplorer).

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.

2. Double-click on the program 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 anexternal filesystem explorer with the appropriate file extension (e.g. .sas) to open a file in theWorkbench editor.

Note: Files not belonging to a Project do not benefit from certain features of the Workbench suchas local history. We recommend that where possible files are opened from within a Project. SeeOpening a Program that is inside a Project.

Opening a Program that is inside a ProjectNote: Ensure you have the Project Explorer view open ( Window ➤ Show View ➤ 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 theprogram in the folder hierarchy.

2. There are two ways to open the file in the editor.• Use the context menu : Right click the program and choose Open With ➤ SAS Editor from

the context menu.• Double-click the program : Simply double-click on the 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 Program thatis outside of a Project.

Getting Help While Writing ProgramsThere are several ways that the Workbench can offer assistance while you are writing a program.


65

Dynamic Help for Language Elements

The Workbench can build a search term to use for searching the Wps Reference for LanguageElements 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 onyour 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 Workbenchthinks it recognises it, the Help view will automatically build a search term to use to search theWPS Reference For Language Elements guide. The search appears in the 'More Results' section ofthe help topic you can see.

3. Click on the search term to perform the search. Relevant topics will be listed in the Help View. Youmay then select these to assist you with writing your program.

4. When you have finished reading the help, click on the Related Topics link (at the top of theHelp view) to return to the context-sensitive help page or the view will not update automatically asyou continue to use the Workbench.

Using Program Content Assist

The SAS Editor provides a content assist feature that can suggest language elements which you canselect 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. 1

2. 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 isdisplayed 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 youwant to use.

5. Double click on the language element you want and it will appear in your program.

Running ProgramsThis section of the guide describes the various ways you can run a program and how to cancel a runbefore it has completed executing.

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 asthe default. The default server (highlighted in bold) is always shown at the top of the list of Servers inthe WPS Server Explorer View. You can run programs on any server, and shortcuts offer a simple andquick way to run them on the default server.

1 (Presently the content assist feature only works for the word PROC)


66

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 selectedpart will be executed and not the whole program.

3. Execute Run by doing one of the following:• From the main menu, select WPS ➤ Run File <pathname> ➤ 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.

While the program is executing, at the bottom right of the Workbench you will see an indication thatthe run is in progress.

Note: For details about various preferences that can be specified with respect to runningprograms, please refer to WPS .

Remember: When you run a program it can interact with other datasets, file references, etc, thathave 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 the context menu:

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 On ➤ 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 thatthe run is in progress.

Note: For details about various preferences that can be specified with respect to runningprograms, please refer to WPS .

Remember: When you run a program it can interact with other datasets, file references, etc, thathave 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:


67

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 WPSServer 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 thatthe run is in progress.

Remember: When you run selected lines from a program they can interact with other datasets,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 servername for Local Server if you are not using the default local server.

2. You can alternatively use the button in the Progress view3. 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 stopimmediately.

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 executablecan be found in the bin directory where WPS was installed. Running wps.exe on its own will not doanything, so you will need to pass it some additional instructions in the following form:

wps.exe <options> <programFileName>

Please refer to the Command Line WPS section for more details about the <options> that can bespecified. Also, the Configuration Files section has more details about configuration files containingsystem options that are used when you run programs.


68

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\WPSPrograms directory. In a command window change directory to where WPS is installed and then to thebin directory. Then type:

wps.exe "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 afile called <programFileName>.lst. For example if we ran a program called Program1.sas, in the samefolder 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 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 isadvisable 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, asabove, is at d:\Work\WPS Programs then you could create a batch file called RunPrograms.batcontaining :

set WPSLOC=C:\Program Files\World Programming WPS 3set 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 orproblems were encountered.

This can be accomplished by redirecting the output of the program to a file. For example, to modify theabove 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 3set 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 viewedwith the text editor of your choice.

Note: Redirecting output in this manner will mean that it will not be shown on the console fromwhich the program was executed.


69

Every time you capture the log information into a file with the same name, the file will be re-created. Inother words, log information is not appended to the same file; it only shows details from the latest run. Ifyou 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 findout if the program executed correctly.

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 canbe 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 bespecified. Also, the Configuration Files section has more details about configuration files containingsystem 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 thebin 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 afile called <programFileName>.lst. For example if we ran a program called Program1.sas, in the samefolder 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 isadvisable 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/wpsexport PRJLOC=/home/user/programs


70

"$WPSLOC/bin/wps" "$PRJLOC/Program1.sas"

Note: The file will need the correct permissions in order to be executable.

To make this batch file run more than one program, copy the last line and modify it to reference the newprogram.

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 orproblems were encountered.

This can be accomplished by redirecting the output of the program to a file. For example, to modify theabove examples to redirect the output to a file called Program1.log change the example code to:

export WPSLOC=/tools/wpsexport 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 viewedwith the text editor of your choice.

Note: Redirecting output in this manner will mean that it will not be shown on the console fromwhich the program was executed.

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 latestrun. If you do wish for the new log to be appended then change the redirection symbol ">" to ">>". Forexample:

"$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 tofind out if the program executed correctly often helps.

Restart ServerIf you wish to clear the log, all results, file references, libraries, datasets, etc., then you need to restartthe WPS Server. Doing so means that programs will no longer be able to interact with any objectscreated 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:


71

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 singularRestart 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 (bydefault Ctrl-Alt-S)

2. A confirmation window may be displayed, allowing you to cancel the restart if you wish. Clicking OKto proceed will clear everything including listing output, HTML output, log, datasets, catalogs, filerefs,etc. for that server.

Notice: You will not see the confirmation dialog if you have seen the dialog before and havechecked 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 theother output.

Restarting with Advanced Server Actions

Warning: This section is only relevant to users who have the Show advanced server actionsoption enabled in the WPS preferences.

If Advanced Server Actions are available, then the context menu for a WPS Server in the WPS ServerExplorer View (and other views that have server nodes) will appear a little different. The followingoptions will be available 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 viewIf you have several programs from different projects open in the Editor view, you can configure theProject Explorer view to automatically expand a project's contents so that the relevant program in theExplorer'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.


2. From the Project Explorer's button bar, click the Link with Editor button.This will toggle this feature either on or off.


72

Working with WPS LinksThis section of the guide describes various tasks associated with managing Host Connection and WPSServer definitions.

The tasks can be performed via the Link Explorer View. Some can be performed from the WPS ➤ Linksmenu.

Creating a New Remote Host ConnectionYou will need to have access to a machine that has a licensed WPS Server installation on a supportedplatform. You will also need to ensure that you have SSH access to the machine, and that you know thelocation of the WPS installation on that machine. You may need to contact the machine administrator toget 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 runningon a supported platform, and harness the power of the server to perform the computation. For moreinformation on the concepts involved see WPS Server.

Note: You do not need any extra software installed on your workstation. In particular you do notneed a separate SSH client installation. It can, however, be useful to have an SSH client installedin order 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 New Server Connection dialog, choose one of:• New SSH Connection (3.1 Compatibility)• New SSH Connection (3.2 and later -- UNIX, MacOSX, Windows)

The first of the above options offers backwards compatibility, having identical behaviour to thatpresent in WPS version 3.1. The second option includes support for establishing remote connectionsto Windows servers running the Bitvise SSH server. Regardless of whether or not you requireBitvise support, you should choose this option if there is no special reason not to.

3. Click Next and in the resulting wizard, type in the hostname or IP address of the remote machineto which you wish to connect. If you wish to specify a port other than the default 22, this can bespecified in the field provided. As you type the hostname, the connection name will automaticallybe changed to that of the hostname, but you can change the connection name to something moresuitable if required (connection names must be unique, so if you are creating multiple connections tothe same host you will need to modify the connection name).


73

4. Enter the user name which you want WPS to make the SSH connection to the remote machine with.5. 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.6. Press Next to define the connection's shortcut directories.


74

Shortcut directories are shortcuts to directories on the remote file system. By default, there areshortcut directories defined for Home (~/) and Root (/). Use the Add... and Remove buttons to editthe list of shortcut directories. Double-click a shortcut to change its definition.

7. If you selected to open the connection immediately, you may be prompted to confirm the identityof the host's RSA fingerprint. If you encounter this dialog, contact your systems administrator. Thefirst time you attempt to connect to a particular host machine you will encounter this message andyou will need to confirm the host key with your systems administrator. Once the host key has beenconfirmed it is stored in the Workbench and subsequent attempts to connect to the same hostmachine will not require this to be reconfirmed. Assuming that the host key is confirmed by yoursystem administrator, then click Yes.

8. If you selected to open the connection immediately you will now most likely be prompted for apassword to authenticate yourself to the host machine. Your systems administrator will haveprovided you with the required password. Enter this password in the entry box in the PasswordRequired dialog and click OK.

There will now be an entry in the Link Explorer view for your new connection. You will now need to addWPS Server definitions to this connection in order to use WPS.


75

Creating a New Local WPS ServerWPS Workbench allows you to have multiple local servers defined on your local connection. For moreinformation on the concepts involved see WPS Server.

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 allconnections.

3. In the tick boxes, indicate whether you would like to start the server immediately, and/or whether youwould 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 thesteps in Local WPS Server Properties to configure startup options for the server.


76

Creating a New Remote WPS ServerWPS Workbench allows you to have multiple remote WPS Servers defined on a remote HostConnection. 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.

2. In the resulting dialog box, enter a name for the server. This name must be unique across allconnections.

3. Enter the path on the remote file-system where WPS is installed. This path will be the root of theinstallation.

4. In the tick boxes, indicate whether you would like to start the server immediately, and whether youwould 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 thenfollow the steps in Remote WPS Server Properties to configure startup options for the server.


77

Exporting Host Connection Definitions to a FileTo simplify sharing Host Connection definitions within a work group, or to enable you to copyconnection definitions between workspaces, you can export connection definitions to a file, which canthen 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....4. 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 distributedamongst your work group, or imported directly into another Workspace on your machine. To import theconnection definitions into a workspace see Importing Host Connection Definitions from a File.

Exporting WPS Server Definitions to a FileTo simplify sharing server definitions within a work group, or to enable you to copy server definitionsbetween workspaces, you can export WPS Server definitions to a file which can then be imported intoanother 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....4. 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 amongstyour work group, or imported directly into another workspace on your machine. To import the serverdefinitions into a workspace see Importing WPS Server Definitions from a File.

Importing Host Connection Definitions from a FileThis task assumes that you have previously exported some connection definitions to a file, or havebeen 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 connectiondefinitions. Connection definition files (*.cdx) can be imported as well as Server Connectionsdefinitions (*.xml) from older versions of WPS.

3. Alternatively, connections can be imported by dragging a Connection Definition File (*.cdx) onto theLink Explorer view.


78

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 withinyour list of connections.

Importing WPS Server Definitions from a FileThis task assumes that you have previously exported some WPS Server definitions to a file, or havebeen 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 isassociated 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

Name2. 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, theimported server definition will be renamed automatically so that it has a unique name within your list ofWPS Servers.

Selecting the Default Server ConnectionWithin the list of WPS Servers that you have defined over all Host Connections, one is always markedas the default server. If you define multiple server definitions you may want to change this default. SeeThe 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 ServerExplorer view and right click to show the context menu. From the context menu select Set asDefault Server. If this option is not enabled, then the selected server is already the default server, oryou selected more than one server.

The selected WPS Server will now be the default server, and will be shown in bold in the WPS ServerExplorer view, and will always appear first in the lists of servers.

Importing DatasetsWPS datasets can be created by importing data from external files. Currently supported formats are:

• Delimited• Fixed Width• Microsoft Excel Spreadsheet Files


79

Important: You can only create datasets in this way on a local WPS Server.

The Dataset Import Wizard allows you to configure the dataset as it is imported. It is not alwaysnecessary to go through all of the steps in the wizard. You may start the wizard and then, havingchosen the file you are importing, simply click the Finish button to accept all the defaults.

Note: If you import a dataset with the same name as an existing member, you will overwrite thatmember. A warning appears in the wizard if this is going to happen, and you have the chance tochange the name of dataset you are creating.

When importing delimited files, the Workbench will attempt to establish which delimiter has been usedin the file automatically. If this delimiter is not correct, you will have the option to change it and thepreview will update to reflect the output that will be generated.

When importing fixed width files, the Workbench will attempt to determine where columns start and endin the data, although you will have the option to alter these as you wish.

Spreadsheet files may contain several worksheets (contained in a workbook). By default, theWorkbench will select the first sheet with data for importing. A sheet may also have names that refer tocell ranges, and it is possible to import data from these names, and also from the clipboard.

Import/Export of Excel spreadsheet files is possible only on Windows local servers. Your PC will needto have the Microsoft ACE OLEDB engine installed to be able to read or write XLSX and XLS formatExcel files. Users that already have Excel installed are likely to have this software already. Windowsusers that do not have Excel installed can download and install the Microsoft Access Database EngineRedistributable. Legacy versions of Excel are also supported, and the Import/Export options areavailable if you have the JET driver installed. However, with the JET driver installed in isolation, you canonly read and write XLS format Excel files.

Importing Datasets From FilesYou will need to have the WPS Server Explorer View open to be able to complete this task.

Note: Importing spreadsheet files is only available on the Microsoft Windows platform. You mustalso have Microsoft ACE or JET engine installed (it is likely that you will have this already if youhave Microsoft Excel installed on your computer).

To import files:

1. Right click the local server and select Import Dataset.You will see the Dataset Import Wizard open.

2. Click the Change button next to the From File text box. Find the file in the file system that you wishto import. Select it and click Open.A preview of the resulting dataset is shown.

3. Ensure that the appropriate option is selected from the Data Format group for the type of file youare importing.

4. Optional: You can change the name of the new dataset, and where it will be stored, using thecontrols on this page.• Change the library you want to store your new dataset in by using the Library Name drop list.


80

• Change the name of the dataset from the default by editing the contents of the Member Nametext box. Using the name of an existing member will overwrite that member with your new data.

5. Click Next to move to the next page within the wizard.6. Optional: This page allows you to configure options specific to the type of import you are performing.

File Format Configuration Options

Delimited The wizard will have made a guess at the delimiter being used in the file. You canoverride the determined delimiter by clicking on the appropriate option.

Fixed Width The wizard will have made a guess at the correct column definitions, but you canalter this now. You can define more columns by clicking in a blank area to separatethat area into two columns, or you can redefine columns by dragging the existingdivisions between them. Dragging a division out of the preview will remove it.

Excel The wizard will have defaulted to import all of the first available sheet in theworkbook with data, although you may alter this now. Choose a different worksheetby selecting one from the Whole Worksheet drop list. Alternatively, you can selecta Named Range from the drop list to use as the data source for importing, if any areavailable.

The preview is updated to reflect any changes you have made.7. Click Use first row as column headers if you know the first row of the file contains column

headers. Examine the preview to determine this.8. Click Next to move to the last page within the wizard.

The Edit Column Properties page is now shown.9. Optional: You can change the properties of the dataset columns if you wish.

• You can change a column name by clicking on the column header in the preview and editing theColumn Name text box contents.

• You can change a column data type by clicking on the column header in the preview andchanging the Column Data Format option.

• You can change a column label by clicking on the column header in the preview and editing theColumn Label text box contents.

10.Optional: Click Next to see the generated program that will be used to create the dataset.11.Press the Finish button to complete the task.

You will see the new dataset appear in the WPS Server Explorer View.

Importing Datasets From Files Using Copy & Paste

You will need to have the WPS Server Explorer View open to be able to complete this task.Note: Importing spreadsheet files is only available on the Microsoft Windows platform. You mustalso have Microsoft ACE or JET engine installed (it is likely that you will have this already if youhave Microsoft Excel installed on your computer).

You can import datasets from files using copy and paste, either from Project Explorer View, FileExplorer View or from outside of the Workbench using your operating system. The example belowexplains how to do this using File Explorer from the Workbench.


81

To start the Dataset Import Wizard by using copy and paste:

1. Find the file in the File Explorer View that you wish to import as a dataset.2. Right click on the file and select Copy from the menu, or use the keyboard shortcut for Copy.3. Find the library into which you want to import your dataset, using the WPS Server Explorer View.4. Right click the library and select Paste, or use the keyboard shortcut for Paste.

You will now be on the first page of the Dataset Import Wizard, with the file and library already chosen.You may then click Finish, or proceed with the remainder of the wizard, to fine tune the import.

See Importing Datasets From Files for more on how to use the wizard.

Importing Datasets From Files Using Drag & Drop


You can import datasets from files using drag and drop, either from Project Explorer View, File ExplorerView or from outside of the Workbench using your operating system. The example below explains howto do this using File Explorer from the Workbench.

To start the Dataset Import Wizard by using drag and drop:

1. Find the file in the File Explorer View that you wish to import as a dataset.2. Find the library into which you want to import your dataset in the WPS Server Explorer View.3. Drag and drop the file from File Explorer onto the library.

You will now be on the first page of the Dataset Import Wizard, with the file and library already chosen.You may then click Finish, or proceed with the remainder of the wizard, to fine tune the import.


Importing Spreadsheet DataYou can import data from Excel spreadsheets. You can import directly from files, in the same way youcan with delimited and fixed files, and you can also import a range of cells you have selected in Excel.

Important: Data imported will have the value it had when the spreadsheet was last saved. If cellsare based on formula, then the formula is not evaluated by the Workbench when the spreadsheetis opened, but the last saved value in the sheet is used.

Importing Datasets From Cell Ranges with Copy & Paste



82

You can import a range of cells directly from Microsoft Excel. A cell range can be copied and pastedonto a library to import only that cell data.

1. Select the contiguous range in your Excel spreadsheet you want to import.2. Press the keyboard shortcut for Copy.3. Find the library where you want to import the data and select it in WPS Server Explorer View.4. Press the keyboard shortcut for Paste.

You will now be on the first page of the Dataset Import Wizard, with the file and library already chosen.You may then click Finish, or proceed with the remainder of the wizard to fine tune the import.

If you click Next instead of Finish, when you reach the Spreadsheet options page, you will notice thatthe Clipboard contents option is already chosen, and the sheet name and range is displayed.


Importing Datasets From Cell Ranges with Drag & Drop


You can import a range of cells directly from Microsoft Excel. A cell range can be dragged and droppedonto a library to import only that cell data.

1. Select the contiguous range in your Excel spreadsheet you want to import.2. Ensure the library you wish to import these cells into is visible in the WPS Server Explorer View.3. Drag and drop the cells onto the library.

You will now be on the first page of the Dataset Import Wizard, with the file and library already chosen.You may then click Finish, or proceed with the remainder of the wizard to fine tune the import.

If you click Next instead of Finish, when you reach the Spreadsheet options page, you will notice thatthe Clipboard contents option is already chosen, and the sheet name and range is displayed.


Exporting DatasetsWPS datasets can be exported as delimited and fixed width text, and also as Microsoft Excelspreadsheets. The Dataset Export Wizard allows you to fine tune the contents of export file asrequired.

To export a dataset:

1. Find the dataset you want to export in the WPS Server Explorer View.2. Right click the dataset and select Export Dataset from the menu.


83

The Dataset Export Wizard will open.3. Choose Delimited, Fixed Width or Excel by clicking the relevant option, if it is not already

selected. For Excel files, choose which Excel format is to be used from the drop list.The Export preview will show how the first few lines of the file will appear for delimited and fixedwidth files.

4. Click Next.5. Optional: You can further configure delimited and fixed width export. If you want to include the

names of the columns, click the Include field names on first row checkbox. Further configurationoptions depend on the export type.ExportType

Options

Delimited Click on the delimiter of your choice, or click Other and type your own in the box provided, if none of the standard delimiters are suitable.

Fixed Width Alter the width of the columns by selecting the column in the drop list, and editingthe Start and Width values.

Any changes you make here are reflected in the Export preview.

Click Next when you are ready to move on to the next step.6. Optional: The default filename is shown, along with the path. You can edit this if you wish, and a

Browse button is available to allow you to find a suitable location for the exported file.7. To open the file once the export is complete, ensure Open when complete is checked. If the

Workbench cannot open the file, it will be opened in the registered application appropriate for youroperating system.

8. If the file already exists, the Confirm replace option will be available, and you will be unableto continue unless it is checked. You can also select the Always replace option, so that theWorkbench will always replace any existing files automatically and just warn you instead. This isuseful if you want to export to the same file several times in the same Workbench session.

9. Optional: Click Next to see the WPS program that the Workbench will run via the server to performthe export.

10.Click Finish.

If you asked for your file to be opened when the export is complete, it may open in the Workbench(depending on the file extension you gave the export file).

Working with the Dataset ViewerThe WPS Dataset Viewer is used for most interactions with the contents of a dataset. The contentsare shown in a grid. The rows of the grid represent dataset observations, and the columns are datasetvariables.

You can view, filter and sort a dataset within the viewer. With some datasets, you can also editobservation variables (i.e. cells), remove observations, and also add new observations.


84

If some of the datagrid columns are irrelevant for a task, you can hide them, and you can re-organise the view by moving columns.

Mode

A dataset is opened in either Browse or Edit mode. By default, a dataset will be in Browse mode unlessyou specifically ask it to be opened for editing.

Note: You can only open WPS WPD datasets in edit mode, and only if nobody else has the samedataset open for editing on another computer.

Opening a Dataset

You will need to have the WPS Server Explorer View open to complete this task.

You can open a dataset as follows:

1. Find the dataset that you wish to open in the WPS Server Explorer View.2. Open the dataset in one of two ways:

• Double click the dataset. It will open in Browse mode.• Right click the dataset and select either Open (browse) or Edit.

Editing a DatasetYou can edit observations, and also add and delete them, if the datagrid is in Edit mode.

Controls for editing a dataset are available from the Data main menu option, from the toolbar, and alsofrom the grid context menu.

If the dataset is open in Browse mode, you can switch to Edit mode by clicking the button:

This Toggle Edit Mode option is also available from the toolbar and from the datagrid right-click menu:


85

Note: You can only edit a dataset that is in Edit mode. You can only use Edit mode on a WPSdataset (a WPD), and only on a server that is running WPS 3.2 or later. It is not possible to edit aview.

You can make as many changes as you like, and abandon them if you wish to by cancelling them. The changes you make are not written back to the original dataset until they are saved. At this point,modifications are made, and observations are then deleted and added.

Note: If saving your changes fails, then any changes that were not written will remain visible inthe grid. You will see an error dialog explaining what happened, and details of the failure will bewritten to the Workbench log. This log can then be used to diagnose the fault.

Modifying Observations

You will need to have a dataset open in Edit mode to complete this task.


86

You can edit observation variables (cells) as raw values. If your variables have any formatting appliedother than the default, you will not see this during your editing. Once your edit is complete, however,you will see the formatted version.

1. Double click the cell that you wish to edit in the grid:

2. How the value is edited depends on the type of the variable.Variable Type Description

Numeric You will see the raw value in an edit box. You can simply typeover this with a new value. If you want to see how the valuecurrently in the edit box will be appear as a formatted value,press Shift + F8 and it will be shown as a tooltip.

Note: Missing values can be entered as text, for example'.A', and the editor will preserve them.

Numeric (Date, DateTime orTime)

Dates, DateTime and Time values are edited as their respectivetypes. You can click on any individual element of a date or time(such as a year or hour) in-place, and use the keyboard arrowkeys or mouse wheel to increase or decrease them in steps.Numeric elements can also be typed over with replacementvalues.

For more intuitive control over the edit, you can use the alternativeedit control associated with each type. Date values have a

calendar, times have a time picker and datetime valueshave a datetime picker combination. Click on the button to theright of the in-place value and the appropriate editor will appear.

String String raw values can be edited in-place in the same way asnumbers. If you want to see how the value currently in the editbox will appear as a formatted value, press Shift + F8 and it willbe shown as a tooltip.


87

3. When you have finished your editing, pressing the Enter key will complete the edit, as will clickingoutside of the cell you are editing.

If the value you entered is different to the original saved value, then the observation is considered to bemodified, and will be shown as such. It will appear in bold type and an asterisk (*) will appear next to theobservation number in the left margin of the grid.

Note: The changes you have made are not actually saved back to the original dataset at thispoint. You need to Save the changes to write them back to the server.

Deleting Observations


To delete observations from a dataset:

1. Select the observation you want to delete by clicking on its observation number in the left handgrid column. If you want to delete multiple observations, hold down CTRL while clicking on theobservation number of the ones you want to delete.The observations should be highlighted, indicating that they are selected.

2. Click the Delete Observation button, from the Data main menu option, the toolbar, or the right-click menu on the datagrid.You will see a warning appear, allowing you to confirm the deletion or cancel it.

3. Click Yes to confirm the deletion.

The data in the cells will be lightly crossed out, and a minus character (-) will appear next to the rownumbers in the left margin of the grid, to indicate that the observations are marked for deletion:


Adding Observations



88

New observations can be added to a dataset. They are always added to the end of the dataset,regardless of your current position within it. To add a new observation:

Click the Add Observation button, from the Data main menu option, the toolbar, or the right-click menu on the datagrid.

The new row will appear in bold type, and a plus character (+) will appear next to the observationnumber in the left margin of the grid, to indicate that the row is new. You may now edit the newobservation to populate the variables if you wish.


Cancelling Changes

You can cancel any edits you have made.

1. Click the Cancel edits button, from the Data main menu option, the toolbar, or the right-clickmenu on the datagrid.The Confirm Cancel Edits dialog will appear.

2. Click Yes to confirm.

Any edits you have made will be cancelled, returning the datagrid to how it was before the changeswere made.

Missing Values


You can set observation variables to missing by using the Set Missing option in the datagrid contextmenu.

Note: When numeric variables are formatted as date, date time or time, this is the only way toset these variables as missing.

1. Select the observation variable (cell) you want to set as missing in the datagrid.Ensure that only one variable is selected. You cannot set several observation variables to missing inone operation.

2. Right-click on the datagrid to display the datagrid context menu.3. Select the Set Missing option from the menu.

4. The Workbench will respond to your command in one of two ways, depending on the variable type.Variable Type Description

Numeric The Set Missing Value dialog will open. If the observationvariable is already set to a missing value, then the current rawvalue is shown, otherwise the missing value will default to '.' (fullstop). You can change the missing value by simply pressingthe keyboard key that corresponds to the value you want to


89

Variable Type Descriptionset. This value can be any of the following: . (full stop), ._ (fullstop followed by an underscore), and .A to .Z. Pressing Enteror clicking the OK button will complete the command. PressingEscape, or clicking Cancel, will return you to the grid with theoriginal value unchanged.

String String variables will be simply set to a single space (' ') characterwhen the option is chosen, and no dialog will appear.

If the value you entered is different to the original saved value, then the observation is considered to bemodified, and will be shown as such. It will appear in bold type and an asterisk (*) will appear next to theobservation number in the left margin of the grid.


Filtering the Dataset View

Filtering a dataset is only possible on a dataset that is on a WPS server version 3.2 or greater. You candetermine the version of your server from the Properties View.

You can filter the contents of the datagrid view by variable, so that you see only the data that you need.Filters are cumulative, so if you filter on more than one variable, then all the various filters will apply.You can cancel any of the filters at any time.

Filters can be applied to a dataset whichever mode it is opened in.

Note: Adding an observation to a dataset while a view is filtered is possible, and the newobservation will be visible while it is being edited, regardless of the contents of the filteredvariables. As soon as the changes to the dataset are saved, any filters are applied, so it ispossible that the new row will disappear from view if it does not meet the currently active criteria.

To filter your dataset view:

1. Click the filter button below the variable heading for the column that you want to filter.The filter criteria menu is shown:


90

2. Select the criteria by which you want to filter the view.Depending on the variable and the criteria chosen, either the filter button is replaced by an editbox below the variable header (numeric and string values), or a dialog with calendar/time controls isdisplayed.

3. Complete the criteria for the filter by entering the appropriate details.Data Type Criteria

Date,datetime ortime

Most expressions based on a date or time variable are set in another dialog. Usethe calendar and clock controls to set the date criteria. For datetime values, clickthe button to set the time component of the filter value.

Othernumeric orstring

The expression for the filter is shown below the variable header. Enter the valueor values necessary to complete the expression in the edit box. For example, tofilter on a numeric variable to show only observations that are less than 100:

LT 100

For a more complete list of the expressions that can be entered, see the reference section Datagrid Filter Expressions.

Once the filter is applied, the filter button icon will change from to , indicating that the variableis now used in a filter.

4. Optional: You can now set any further filter criteria on other columns by following the steps above.


91

5. Optional: You can clear the filter for a variable by clicking on the filter button again, and thenclicking on the Clear Filter menu option.

As you apply and cancel filters, the datagrid contents will update to honour the criteria set.

Sorting a dataset

Sorting a dataset is only possible on a dataset that is on a WPS server version 3.2 or later.Note: The version of your server is displayed in the Properties view when you select the serverin the WPS Server Explorer View view.

Note: Sorting is not available if the dataset is open in Edit mode.

You can sort the contents of a dataset on several variables. Variables that are part of an active sorthave an icon representing the direction of the sort in the header. The size of the icon indicates thesignificance of the variable in the sort. The or icon represents the sort primary key, the or the secondary key, and the or icon the tertiary and subsequent keys.

Note: If you attempt to switch to Edit mode while a sort is currently active, a warning will bedisplayed. This is because to go into Edit mode would require the entire dataset to be rewrittenin accordance with the current sort order, to allow it to be edited in-place. If you require this, clickYes in the dialog, but you must be aware that this will re-write the entire dataset on the server inthe order you have set in the grid, and put the grid into Edit mode. If you do not required this, clickNo.

You can sort a dataset as follows:

1. Right click the column header for the variable that you wish to use as the primary key.The column header menu will appear.

2. Click on either Ascending Sort or Descending Sort to perform the sort.The grid data is now sorted in the order requested.

3. Optional: You can now add secondary and subsequent keys to the sort by following the stepsabove.

4. Optional: You can clear any of the sorts by using the Clear Sort option from the context menu forthe associated variable.

Organising the Dataset ViewYou can manipulate the grid so that you hide variables you do not need, and you can move columns sothat they are in a different order. These changes affect only your view of the data and do not affect thedata itself.

Hiding Dataset Variables

To hide a datagrid column:

1. Right click the column header in the datagrid for the variable you want to hide.


92

The column header menu will appear.2. Click Hide column(s).

The datagrid column will disappear from the view.Note: If you attempt to hide a column for which filtering is currently active, then you will beasked to confirm that you wish to remove the filtering and hide the column. Click Yes or No asappropriate.

Showing Previously Hidden Dataset Variables

To show previously hidden dataset variables:

1. Right click the column header in the datagrid for the variable that you want to show.The column header menu will appear.

2. Click Show / Hide Columns....The Show / Hide Columns dialog will appear, showing check boxes for the displayed columns(these are ticked), and for the hidden columns (these are not ticked).

3. To show a column that was previously hidden, tick its check box.4. Click OK.

The columns displayed reflect the changes made in the Show / Hide Columns dialog.

Moving Dataset View Columns

You can move dataset columns to wherever you wish within the grid, despite the order of the columnsin the dataset. Doing this will not change the physical order of the columns on the server, only yourcurrent view of them.

To move a column:

1. Left click and hold the mouse button down on the column header.2. With the mouse button still held down, drag the column towards where you would like it to be.

As you drag the column left or right, the column header will become translucent. You will see a thickgrey line appear between columns, indicating where the column will appear if you release the leftmouse button:


93

3. Release the left mouse button when the grey line is in the correct place.

The column will appear in the new position.

Working with Program OutputThis section of the guide looks at the features for locating and manipulating the results (HTML andlisting), logs and datasets that are generated as a result of running a program.

Working with the LogThis 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 ➤ OutputExplorer).

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 existinglog text. You can Clear the Log to ensure that when you next run a program, the log only containsinformation 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 ina log viewed in the Workbench. Please refer to WPS Log Syntax Coloring preferences for moredetails.

If you have more than one WPS Server registered in the Workbench then a separate log window willbe opened for each server log that you view.


94

Navigating the Log

If you have performed several runs and have not used Restart Server or Clear the Log, theneach 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 ➤ 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 correspondingsection in the log file will be displayed.

Saving the Log to a File

There are several ways to save the log to a file:


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 Save As…. With the log open in the editor you can also use the File ➤ SaveAs... menu option.

Printing the Log

To print the log, open the log file and select 'Print...' from the 'File' menu. Alternatively, right-click on thelog file viewer itself and select Print... or right-click on the Log in the Output Explorer and select PrintLog....

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 standardworkstation installation of WPS Workbench, then the Clear Log action will always clear the logfor that server.

Tip: If you have more than one WPS Server registered then the Clear Log menu action will clearthe log for the default server unless a different server or server log is selected and has focus. If indoubt use the tooltip for the toolbar button to show which log will be cleared.

Working with Listing OutputThis section of the guide looks at the features for locating and manipulating the listing output.


95

Viewing the Listing Output

To view the listing output:


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:• Clearing the Results Output (which will also clear any HTML output)• Restart Server (which will clear the log, all results, datasets, library and file references etc.)

If you have more than one WPS Server registered in the Workbench then a separate listing windowwill 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 ➤ 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 willbe 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 themenu item Window ➤ Show View ➤ 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 thelisting window and select Save As….

Printing the Listing Results

First ensure you have the Viewing the Listing Output open, and that it has the focus, and then do one ofthe following:

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....


96

Working with HTML OutputThis section of the guide looks at the features for locating and manipulating the HTML output.

Viewing HTML Output

To view HTML output:


2. Expand the WPS Server node for which you wish to view output, so you can see the HTMLnode.

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 Outputsection 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) theneach run will create a new HTML file. The outline view of the HTML output provides access to all HTMLoutput 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 ➤ 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 outputwill 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 viewto 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.

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 selectingPrint Results... from the pop-up menu.


97

Note: A single HTML output file is created for each run within the Workbench. You can only printthe HTML output of one run at a time. See Running a Program for more information about runs.

Clearing the Results OutputTo 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 standardworkstation installation of WPS Workbench, then the Clear Results action will always clear allresults for that server.

Tip: If you have more than one WPS Server registered then the Clear Results menu action willclear all the results for the default server unless a different server is selected and has focus. If indoubt use the tooltip for the toolbar button to show which results will be cleared.

Working with DatasetsThis section of the guide looks at the features for locating and manipulating datasets.

Viewing the Contents of a Dataset

To display the observations contained in a dataset:

1. Ensure you have the WPS Server Explorer view open ( Window ➤ Show View ➤ WPSServer Explorer).

2. Expand the tree view under the Libraries node until you can see the dataset node you wish toopen.

3. Right mouse click on the dataset node and from the popup menu select Open.4. Alternatively double-click on the dataset node.

Tip: You can display labels in the column headers of a dataset you are viewing in theWorkbench. Please refer to WPS Dataset Viewer preferences for more details.

Clearing the Datasets

You cannot just clear the datasets on their own. The process to clear datasets, unavoidably meansthat you also end up clearing all the other output such as the HTML output, listing output, log entries,libraries, file references, etc.

In order to clear all the output, you need to use the Restart Server feature.


98

Analysing Programs and Language ElementsThis 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 analyserdoes not actually execute programs to perform an analysis and generate a report. The analyser will stillreport 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 thelanguage 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 listof the macro language elements and the library engines and options that are supported by this releaseof WPS, please refer to the Macro Processor and Library Engine sections in theWPS Reference ForLanguage Elements guide.

When generating Program Compatibility reports (refer to Analysis Reports), if the analyserencounters an unsupported procedure, it just reports that as a problem and does not report on anyof that particular procedure's options that have been used. However, when generating LanguageUsage reports (refer again to Analysis Reports), the same unsupported procedure is reported alongwith any unsupported options that were also encountered.

Although WPS Workbench cannot be used on a mainframe the Language Analyser can still be used tocheck programs for this operating system.

Analyse Mainframe ProgramsThe code analyser is a feature of the Workbench and cannot therefore be used on platforms on whichthe Workbench is not supported. However, if Programs are moved from a Mainframe to a systemrunning the Workbench, the code analyser is still able to report on all language elements includingthose specific to the z/OS platform.

When programs are moved from a mainframe to a non-mainframe (distributed) system, note that beforethe 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

Refer to the Analysis Restrictions section for more details about analysing your programs.


99

Once you have moved your Mainframe programs to the Windows platform, you can either AnalyseProgram Compatibility or Analyse Language Usage .

Analyse Program CompatibilityTo analyse one or more programs to see if the language elements they contain are supported in thisrelease 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 ➤ Project Explorer.• Use the File Explorer View. You open this view from the main menu via Window ➤ Show View

➤ 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 Program Compatibility Analysis report will automatically open inthe Workbench.

Related Topics:

• Analysis Restrictions• Navigating Analysis Reports• Export Analysis Results to Excel

Analyse Language UsageTo 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 ➤ Project Explorer .• Use the File Explorer View. You open this view from the main menu via Window ➤ Show View

➤ 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 selectFile ➤ Analyse ➤ Language Usage.


100

When the analysis has finished, a Language Usage Analysis report will automatically open in theWorkbench.

Related Topics:

• Analysis Restrictions• Navigating Analysis Reports• Export Analysis Results to Excel

Opening Analysis ReportsAn 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 Program Compatibility Analysis report, or a Language Usage Analysis report. Both types of reportwill only display the results of the latest analysis. In other words, you cannot have open more than oneof each type of analysis report.

Once you close an analysis report, it is lost until you either re-run the analysis again or you ExportAnalysis 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 pageof 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 youcan click to drill back up to the previous page.

Expanding and Collapsing Report Sections

Expanding: If you see an icon to the left of a title, you can click on this to expand that section of thereport.

Collapsing: If you see an icon to the left of a title, you can click on this to collapse (or hide) thatsection of the report.

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 oflocations where the language element occurs in a program. Click on one of these locations to open theappropriate program at the line where the language element occurs.


101

Export Analysis Results to ExcelThe 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 thefollowing:• 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 MarkersThe Workbench has two types of marker with which you can work: bookmarks and tasks.

Working with BookmarksThe Workbench has facilities that allow you to add Bookmarks inside a program. The Workbenchprovides you with tools to create, manage and navigate between bookmarks.


Adding a Bookmark

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 ➤ 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.


102

Navigating Between Bookmarks

To navigate between the various bookmarks (i.e. display the program at the appropriate line in theeditor window):

1. Open the Bookmarks view ( Window ➤ Show View ➤ Bookmarks).2. Right-mouse click anywhere on the bookmark Description 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 TasksThe Workbench has a facility that allow you to add Tasks inside a program. The Workbenchprovides you with tools to create, manage and navigate between task markers.


Adding a Task

To add a new task marker 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 a task marker in the border.

Deleting a Task

To delete a task:

1. Open the Tasks view ( Window ➤ 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 markers (i.e. display the program at the appropriate line in theeditor window):

1. Open the Tasks view (Window ➤ Show View ➤ Tasks).2. Right mouse click anywhere on the task line and from the popup menu select Go To.


103

Double clicking on the line will also open it.3. The program will open (if it was closed) and scroll to the appropriate line.

Working with Local HistoryThe Workbench maintains a Local History about the edits and deletions of programs within Projectsmanipulated in the Workbench. This history can be used to compare or even revert to previousversions of the same program.

This section of the guide discusses using this feature.


Compare with Local HistoryTo 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….A window opens showing the list of program revisions.

3. From the list of revisions, double click a particular revision to compare with. The date and time ofthe 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 thedifferences.

5. Click the OK button when you have finished comparing.


Replace with Local HistoryTo 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….A window opens showing the list of program revisions.

3. 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 currentversion is titled Workspace File, and the revision you selected is titled Local History.


104

4. (Optional) You could just highlight and copy a portion of text from a previous version and then pressthe Close button in the window's upper right hand corner. Now you can paste your piece of text intoanother program.

5. 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 toa Workbench Project.


Restore from Local HistoryA program or any other file that has been deleted using the Workbench's delete facility can beundeleted:


2. Right click on a folder or project and from the popup menu select Restore from LocalHistory... .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 local history list on the right hand side of the dialog.Revisions 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 Size and DurationBy default, the Workbench keeps seven days of local history for each individual Project program anda maximum of fifty entries per program. There is also a default of 1 MB of storage allocated for eachprogram's local history.

All of these settings can be changed and are discussed in the General Local History preferencessection.



105

WPS Tips and TricksUsing ODBC : Learn how to use an ODBC connection in a program.

WPS Dataset Viewer: Make your datasets 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.


106

Reference

License KeyWPS requires a valid license key to operate. Only when a license key has been applied will you beable to use WPS to run any programs written in language of SAS. A license key is provided in a fileending in .wpskey that is separate from the WPS installation file.

This section of the guide looks at how you can apply a new licence key or how to look up the details ofthe license key that is already applied to your installation.

Applying a License KeyTo apply a new license key to your WPS installation:

1. Select the Workbench menu item Help ➤ Apply License. The Apply License window will bedisplayed.

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, then, before applying alicense key, ensure that you have administrator privileges on your computer.

Viewing Your Applied License DetailsTo 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 windowwill be displayed.

2. When you wish to close this window, click on the OK button.

PreferencesThere are many user settings, controls and defaults that you can adjust and specify from theWindow ➤ Preferences… panel.

In this section of the guide, we will focus on those preferences that have an effect on how Programsare edited, displayed, run, etc. Any preference that is not described in this guide can be looked up in theEclipse-specific Workbench User Guide.

Preference FilterThe preferences window has a filter function which can help you find preference pages quickly:


107

Once you have opened the Window ➤ Preferences… panel, you can see the filter function near the topleft. It is a text box with the words type filter text.

By way of an example, type the word log into this box one letter at a time and see how the preferencewindow filters the available pages whose title contain the text you have typed in as a filter.

To stop filtering, click on the Clear button and you will see all available preference items re-displayedin the tree view.

GeneralUnder Window ➤ Preferences… ➤ General are controls that not only affect Programs, but alsoaffect other types of files and other general aspects of the Workbench. Here are some of the items thatyou can control that have an effect on programs:

Always Run in Background: Some operations such as running a program, or refreshing a projectcontaining a lot of files, can take a long time to execute. When the Run in Background option isenabled, it allows such tasks to execute without displaying the Executing dialogue window. If thisoption is left unchecked, the dialog box that appears when running a program has a button thatwill run that program in the background.

Show heap status: When this option is selected the amount of memory that WPS Workbench is usingappears in the bottom right corner of the window.

Open Mode: This preference controls the way you open on objects in the Workbench with either asingle click or a double click of your mouse.

General Local HistoryUnder Window ➤ Preferences… ➤ General ➤ Workspace ➤ Local History are the controls that youcan set regarding the Local History.

Days to Keep Files: The number of days that you want to keep records for any one program. Forexample, 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 thenumber 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 shouldbe kept. If the size of the program exceeds the maximum amount of file size allocated, no localhistory is kept for it. The default size is 1MB.

General Text EditorsUnder Window ➤ Preferences… ➤ General ➤ Editors ➤ Text Editors you can set the properties ofeditors. This affects the editing or viewing of programs. Some examples of these properties are:

• Tab Width


108

• Undo history size (i.e. size of the 'undo' buffer in terms of the number of operations able to beundone)

• Colours (current line, foreground, background, etc)• Show line numbers

Note: Details about the colours used to display language elements in a program can be lookedup or defined under the WPS Syntax Coloring preferences.

General Text File EncodingIn order to display and save programs and files that contain non English characters, you may need toset 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-8.4. 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 can type in the required encoding in the Other field if you do not see the requiredoption in the drop-down list. If your selection is valid, it is saved when you click OK.

Note: It is also recommended that, in all cases, you check that the LOCALE is set for yourcountry so that data is handled correctly by the WPS server. To do this, ensure that the server isstarted and that the LOCALE displayed in the bottom right hand corner of the Workbench is setappropriately (e.g. to "fr-FR"). If not, proceed as in WPS Server LOCALE Setting.

Setting Encoding at a Project Level

To set an encoding value only for programs contained in a specific project:


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. 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.


109

Note: You may want to also specify an appropriate WPS Server LOCALE Setting.

WPSUnder Window ➤ Preferences… ➤ WPS are the controls that control some general aspects of the WPSWorkbench behaviour:

Save all modified files before running a program: This preference controls whether WPS will saveany modified programs before a program is run. The behaviour can be one of : Always, Neveror Prompt. The default for this option is Prompt. This causes a dialog to be shown wheneveryou attempt to run a program. If you have a complex program that consists of a number of sourcefiles then it is recommended that this preference be set to Always. Consider the case where youmight have two source files and the first uses a %INCLUDE statement to include the contents ofthe second. This is one method in which a large program can be built up from a number of smallersource files. In this case the %INCLUDE will read the contents of the file as they appear on thedisk, and any unsaved changes that you might have in the program editor will not be seen by yourprogram. When you are editing a program and run it using the Run button however, it is thecurrent content of the editor window that is submitted, and not the contents of the file, so unsavedchanges will be executed.

Close all open datasets before running a program: Sets how WPS deals with closing open datasetswhen running a program. The behaviour can be one of: Always, Never or Prompt. The defaultfor this option is Prompt. Having datasets open in the dataset viewer can cause problems if youattempt to run a program that will overwrite the same open dataset with a new version. For thisreason 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 logfile when an error is encountered in a program. The behaviour can be one of: Always, Never orPrompt. The default for this option is Prompt which causes a prompt to be shown the first time anerror is encountered in a running program.

Close all open datasets when deassigning a library: Controls whether WPS will automatically closeany datasets that may be open in a library when you deassign a library by selecting the Deleteitem from the context menu in the WPS Server Explorer view. The behaviour can be oneof: Always, Prompt. The default for this option is Prompt which will cause a prompt when youattempt to deassign a library and there are datasets 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 followingactions:

• delete a server definition• delete a dataset, catalog or view from within a library• de-assign a library• de-assign a fileref• delete a catalog entry from within a catalog


110

Confirm server restart: This option controls whether WPS will ask for confirmation when you select aserver in the WPS Server Explorer and restart the server from the context menu.

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 temporaryfiles. The log files created during execution of a program are stored in this directory, as are anyODS HTML results generated by a program. You may find that you need to modify this setting ifthe default value points to a location with space restrictions. Log files created during execution canbe large, and you may find you encounter space problems.

Show advanced server actions: This option controls the context menu options available whenrestarting WPS servers. If checked, extra options appear in the context menu of a WPS server inseveral of the Workbench views. These allow you to restart and keep the contents of your WORKlibrary, or to perform a restart that will clear it (as is normal).

WPS Code InjectionUnder Window ➤ Preferences… ➤ WPS ➤ Code Injection are the controls that allows for code to berun automatically before and after any program.

Enable custom pre-code injection: When this option is enabled the code in the following text boxis executed before any program is run. This option provides a facility similar to the INITSTMTsystem 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 WPSResult Options controls whether code is automatically injected to set up ODS destinations so thatyou can easily view the results of your programs in, for example, HTML. However the set up thatit performs may not be suitable for you, and in that case you can use the custom code injectionfacility 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 boxis executed after any program is run. This option provides a facility similar to the TERMSTMTsystem option, except here the code is automatically run after each program that is submitted. TheTERMSTMT system option is only processed on server shutdown.

WPS Code TemplatesWindow ➤ 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 tempCtrl+space and the code completion feature will execute the following actions:• Match temp against the list of code templates.• Find your template called template1.• 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 aselection dialog to choose which template you would like to substitute.


111

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 datasetfor which the name is difficult to type. A code template could also define a large amount of text. Forexample, a boilerplate invocation of a particular procedure.

You can export code templates to an external file, or import them from a previously exported file. Thisallows you to share code templates with colleagues, or to copy code templates that you have definedbetween workspaces.

WPS Dataset ViewerUnder Window ➤ Preferences… ➤ WPS ➤ Dataset Viewer you can set your default preferencesconcerned with viewing a dataset in the Workbench.

Show labels for column names: Toggle on/off the option to display labels in the column headers of adataset that is viewed in the Workbench rather than the column names.

WPS File ExplorerUnder Window ➤ Preferences… ➤ WPS ➤ File Explorer are the preferences you can set regardinghow the file explorer behaves.

Select Show hidden files and folders to ensure that files and folders starting with a '.' character (forUNIX based systems) or hidden Windows files/folders are displayed. Hidden files and folders on aremote Windows based system will not be affected by this preference switch.

WPS Result OptionsUnder 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 (OutputDelivery System) destinations set up by default, and all procedure output will come out in theLISTING destination. This behaviour reflects what happens when you run a WPS program froman operating system command line using the wps executable. You may want to use this settingif you have programs that are ultimately designed to be run from the command line and set uptheir own ODS destinations. If this preference is set to Yes, then the Workbench will automaticallymanage 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 programis submitted.

Note: Even if automatic management is chosen it is still possible to define custom ODSdestinations as usual.

WPS Syntax ColoringUnder Window ➤ Preferences… ➤ WPS ➤ Syntax Coloring are controls you can specify regardinghow 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 orItalic.


112

WPS Log Syntax ColoringUnder Window ➤ Preferences… ➤ WPS ➤ Log Syntax Coloring are the preferences you can setregarding how to display the different items contained in a log file (e.g. errors, notes, warnings, etc).

For each different type of item contained in a log, you can specify attributes for Color, BackgroundColor and if the item should be displayed in Bold.

Backing Up Your PreferencesTo 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 NavigatingThere is a wealth of tools and functions provided by the Workbench to help with editing and navigating

Programs. In this section of the guide we will look at some of the more commonly used features.

Undo and Redo Your EditsYou can undo program edits step by step by using the main menu option Edit ➤ Undo (or pressCTRL + Z on your keyboard).

You can step through re-doing any undone edits by using the main menu option Edit ➤ Redo (orpress CTRL + Y on your keyboard).

FindYou can find any text string in an individual program that you have open by using the main menuoption 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 ForwardThe main menu options Navigate ➤ Back and Navigate ➤ Forward are analogous to the backand 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 navigationalinformation.


113

Go To Your Last EditThe 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.• Place your edit cursor at the end of the piece of text you edited.

Next and Previous AnnotationAlthough the menu items Next Annotation and Previous Annotation would appear to imply that thisfeature is for annotations only, you can actually use these controls to navigate between annotations andquick 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 differentin 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 menuoptions Navigate ➤ Next and Navigate ➤ Previous (or press the respective keyboard optionsCTRL + . and CTRL + ,).

As well as using these menu and keyboard options, you can also use the buttons in the Workbench'smain 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 navigatebetween.

Host Connection PropertiesThere are many properties that you can set and adjust that help specialise how a Host Connectionbehaves. The properties available differ slightly depending on whether your connection is local or


114

remote and whether the connection is currently open or not (see WPS Server for more informationabout local and remote connections). Connection properties are accessed by selecting the connectionyou wish to change the properties of in the Link Explorer View, then by right clicking and selectingProperties from the context menu.

Depending on whether your connection is a local or remote, please continue by selecting the relevanttopic below.

Local Host Connection PropertiesThe following properties and information are available for a local connection.

Shortcut Directories (available for open connections only): A local Shortcut Directory is a shortcutto a directory on the local file-system. The local Shortcut Directories that are created by defaultdiffer in accordance with the operating system on which you are running the Workbench:

For Windows users. There will be 'Home' and 'Workspace' shortcuts, and also a shortcut for each availablelocal disk drive. For example, if you have drives 'C' and 'D' on your computer, there will be four ShortcutDirectories by default.

For users on other Operating Systems. Only the 'Home' and 'Root' shortcuts will be created by default.

Other shortcuts can be added, edited and removed from this properties page. Shortcut Directories canbe explored in the File Explorer view.

Note: For Windows users, local Shortcut Directories may only be created if the Local Servercomponent has been installed.

Remote Host Connection PropertiesThe following properties and information are available for a remote connection. The list of items onthe left of the Properties dialog are explained below. Some items are only available when the server isrunning, 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 username you wish to connect to it with.

• The Automatically open connection check box controls whether the connection is automaticallyopened when the Workbench is started up.

• The Enable Compression check box controls whether the ssh connection , and as a result theprotocol traffic between the Workbench and the remote connection, is compressed or not.

• The Use SSH Port Forwarding check box controls whether or not the ssh connection uses sshport forwarding to send standard in and out information between the remote connection andthe Workbench. This requires your ssh daemon to be running with "AllowTcpForwardingyes" specified in the config file. If this is not enabled in your ssh daemon configuration youshould 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 theHostname entry exists. If you are in the process of setting up the remote host, or you knowthat it will exist at some point, then you can uncheck this check box and the Workbench will


115

allow you to save the settings. Otherwise you will get an error and will be required to specifya host that exists.

Advanced Connection Options: There are circumstances where it is necessary to control the list ofenvironment variables that the remote server will inherit when it is started. By default the serverprocess will just inherit the default interactive shell environment for the user under whose IDthe server is being started. An example would be the environment variables required in order touse a database library engine. On Linux, for example, this might require that the database clientshared libraries be added to the LD_LIBRARY_PATH so that they can be loaded by the WPSsoftware. One way to do this is to modify the /etc/profile or ~/.profile file in order to addthe required directories to the LD_LIBRARY_PATH. However this may not always be desirable.An alternative on UNIX/Linux is to place a wpsenv.sh file in the WPS installation directory, orin your home directory. Its contents will be automatically run before the server is launched. Theoutput from any commands that you execute in this way can be seen in the Console View. OnWindows, if you want the WPS server to acquire any special environment variables, you will needto configure them in the normal way - by using the Control Panel to set them either as systemenvironment variables or specific to the relevant user. All processes running as that user willsee those variables, and there is no way to specify that they should only be visible to the WPSprocess.

Shortcut Directories (available for open connections only): A shortcut directory is a shortcut toa directory on the remote file-system. By default, there are shortcut directories defined for yourhome 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 FileExplorer view.

WPS Server PropertiesThere are many properties that you can set and adjust that help specialise how the WPS Serverbehaves. 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 byright clicking and selecting Properties from the context menu.

Depending on whether your server is a local or remote server please continue by selecting the relevanttopic below.

Local WPS Server PropertiesThe following properties and information are available for a local server. The list of items on the left ofthe 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.

Code Submission: If, before any program is submitted to the server, you require the working directoryon the server to be set to be the same as the directory from which the program is opened,select the option shown here (Set the server working directory to program directory on


116

submission). This setting of the working directory should then happen automatically provided thatthe directories are on the same host. If the directories are not on the same host, then the workingdirectory on the server is set to be the Initial current directory for server process specified inStartup (see below). If the option Set the server working directory to program directory onsubmission is not selected, then no changes are made to the working directory when a programis submitted to the server.

Environment: This lists the environment variables that are set on the local machine. This is notmodifiable here and is purely for information. This item is only available when the server isrunning.

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 theserver is running.

Startup: The server can be configured to start automatically when its connection starts by selectingStart the server automatically on connection startup. The Initial current directory for serverprocess entry is where you specify the working directory for the server, i.e. where the serverconsiders itself to be running from. It can affect things such as the locations to which output isgenerated. If you have %INCLUDE statements in your code with relative paths in them, then it isimportant that you start the server in the correct directory to allow those %INCLUDE statementsto find the files they are including. The Startup page has two further sub-pages, EnvironmentVariables and System Options:

Environment Variables. This section permits you to specify any environment variables that you would likeset before the server is started. By clicking the New button you can specify an environment variablename and the value you would like it set to. The item will then appear in the list. You can also thenEdit... and Remove any environment variables you have created.

System Options. The Startup System Options page is where you can specify any WPS options that youwould like to pass the server to process on startup. The options available here are typically any of thosethat can be passed directly to WPS on the command line. If you click Add... you will see a new popupdialog 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 optionvalue (below the option name), and then click OK to save it. The value chosen is then visible in the localserver 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 currently set on the server,along with their values. This is the same information you would get if you ran a PROC OPTIONSstatement. This is not modifiable here and is purely for information. This item is only availablewhen the server is running.

WPS License Information: This shows the setinit information for the server, such as the productsthat are licensed, the amount of grace or warning time on the license, and the date that the licenseexpires. This item is only available when the server is running.

WPS Software Information: This lists information about the local WPS Server itself, such as itsversion and the operating system it is running on. This is not modifiable here and is purely forinformation. This item is only available when the server is running.


117

Remote WPS Server PropertiesThe following properties and information are available for a remote server. The list of items on the leftof 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.

Code Submission: If, before any program is submitted to the server, you require the working directoryon the server to be set to be the same as the directory from which the program is opened,select the option shown here (Set the server working directory to program directory onsubmission). This setting of the working directory should then happen automatically provided thatthe directories are on the same host. If the directories are not on the same host, then the workingdirectory on the server is set to be the Initial current directory for server process specified inStartup (see below). If the option Set the server working directory to program directory onsubmission is not selected, then no changes are made to the working directory when a programis submitted to the server.

Environment: This lists the environment variables that are set on the remote machine. This is notmodifiable here and is purely for information. This item is only available when the server isrunning.

Macro Variables: This lists the macro variables and their values that are set on the remote WPSServer. This is not modifiable here and is purely for information. This item is only available whenthe server is running.

Startup: The server can be configured to start automatically when its connection starts by selectingStart the server automatically on connection startup. The Working directory for executionentry is where you specify the working directory for the remote server. This is where the serverconsiders itself to be running from. This can affect things such as the locations to which output isgenerated. If you have %INCLUDE statements in your code with relative paths in them, then it isimportant that you start the server in the correct directory, to allow those %INCLUDE statements tofind the files they are including. The Startup page has one further sub-page, the System Optionspage.

System Options: The Startup System Options page is where you can specify any WPS optionsthat you would like to pass the server to process on startup. The options available here aretypically any of those that can be passed directly to WPS on the command line. If you clickAdd... you will get a new popup dialog that lists all the options that can be set. Select theoption you wish to set and click OK and you will see it added to the list. You can then edit thevalue 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 currently set on the server,along with their values. This is the same information you would get if you ran a PROC OPTIONSstatement. This is not modifiable here and is purely for information. This item is only availablewhen the server is running.

WPS License Information: This shows the setinit information for the server, such as the products thatare licensed, the amount of grace or warning time on the license, and the date that the licenseexpires. This item is only available when the server is running.


118

WPS Software Information: This lists information about the server itself, such as its version and theoperating system it is running on. This is not modifiable here and is purely for information. Thisitem is only available when the server is running.

WPS Server LOCALE SettingThe locale used by WPS is set individually by server. Local and remote server properties are set usingthe 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. Rightclick and select the Properties item in the popup menu. The Properties window will be displayedfor 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.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 separate guide entitled WPS Reference forLanguage Elements in the LOCALE Values section.

7. Now, select the OK button on the Properties window and you will be prompted to restart the serverto apply your changes.

Note: In order to display and save programs and other files that contain characters for yourselected LOCALE, you may need to set an appropriate General Text File Encoding value. Alist of valid ENCODING values can be found in the separate guide entitled WPS Reference forLanguage Elements in the ENCODING Values section.

Note: Any LOCALE option defined in any external Configuration Files will be ignored. You mustset LOCALE as a Workbench startup option, as described above, in order for it to be used frominside the graphical user interface. When using Command Line WPS to run programs in batchmode, then the startup option is ignored and the LOCALE option in the external config file is usedinstead.

WPS WORK LocationTo set the language system option for the WORK location that you wish to use every time you startuplocal or remote server:

1. In the WPS Server Explorer pane, place the cursor over the relevant local or remote server. Rightclick 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, expand the Startup node, and then click the SystemOptions node.


119

3. On the right of the dialog, you should now click on the Add... button. The Startup Option dialog boxwill 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. Theoption 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 boxand then select the OK button. You should now see the WORK option and it's associated valuelisted 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 serverto apply your changes.

Note: Any WORK option defined in any external Configuration Files will be ignored. You must setWORK as a Workbench startup option, as described above, in order for it to be used from inside thegraphical user interface. When using Command Line WPS to run programs in batch mode, thenthe startup option is ignored and the WORK option in the external config file is used instead.

Using ODBCAlthough 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 inthis guide for convenience to readers. For full details of the libname language element, please consultthe WPS Reference For Language Elements guide.

ODBC can be used to connect many different types of data source. By way of an example we willdiscuss 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 connectionto 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 dataset calledpeople, and you will then be able to browse the local dataset from the Workbench.

WPS also supports the schema option on libname:

libname lib ODBC dsn=<odbc-datasource-name> user=<userid> pwd=<password> schema=<myschema>;


120

and then when you say:

data people;set lib.employee;

it refers to the table in <myschema>.

Command Line WPSBesides being able to use WPS in Workbench mode (i.e. from the graphical user interface), you canalso use the system in command line mode. This provides a way of running programs outside of theWorkbench, which is often referred to as running in batch mode.

In this mode, you cannot compile programs into run-time jobs.

To use WPS from a command line you need to execute wps.exe on Windows, or wps on any of theUNIX-based platforms. This executable is located in the /bin directory of the WPS installation. Thefollowing examples assume a Windows environment, hence the use of wps.exe.

wps.exe <options> <programFileName>

The <options> can be a list of any of:

• -optionname [optionalValue]

• -config <configFileName>

• -set <envVarName> <envVarValue>

Programs

When you run a program using wps, the <programFileName> should always be the last parameteryou define. In fact, when wps executes, the first parameter that is encountered which does not start witha 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.Note: You can only pass wps single value options on the command line. It does not allowparentheses. You can quote values with spaces in, but the quotes will be removed.


121

Configuration Files

System options can be defined in a configuration (config) file, and this file can be explicitly referencedwhen executing wps:

wps.exe -config <configFileName> <programFileName>

Please refer to the Configuration Files section for a more detailed discussion about configuration filesand the order in which they are processed.

Note: When running program using wps, any WPS Server Properties that have been setup as apreference 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 inthe command line. It does not allow parentheses.

Output

Log Information: When you run a program with wps, the log information about the run is automaticallysent to the DOS window in which WPS is running. Once the program has finished running and theDOS window closes, this log information is lost. To capture the log information you need to send itto an external file:

wps.exe <options> <programFileName> <logFileName>

Capturing the log information in this way means it will no longer be displayed in the DOS windowas the program is running. Every time you capture the log information into a file with the samename, the file will be re-created. In other words, log information is not appended to the same file; itonly shows details from the latest run.

Results Output: When a program is run using wps, any results generated by the program areautomatically captured into a file called <programFileName>.lst created in the same directoryas the program. For example we would get a file called Program1.lst if we ran a program calledProgram1.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 Runa Program on the Command Line in Windows and Run a Program on the Command Line in a Non-Windows Operating System.


122

Configuration FilesConfiguration 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, andwhen 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 changesystem options to suit your needs.

There is a base configuration file that is included with the WPS installation, called wps.cfg and it islocated in the directory where WPS is installed. It is recommended that this file be left untouched andone 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 setsome of the same options. If an option is set in more than one place, the last one processed will haveprecedence. Options set on the command line, or options set in the Startup Options configurationpanel 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 thespecified configuration file is processed first. The processing of this file does not affect whether thedefault configuration files are loaded.

2. Any files specified via the -config option on the command line, or specified in the Startup Optionsconfiguration 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, andinstead the process jumps straight to the processing of WPS_USER_CONFIG at step 4.

Note: Overriding the default configuration file processing, specifically the loading of the wps.cfgfile in the WPS installation directory, must be done with care. There are many required optionsin the base wps.cfg file. If you choose to use the -config option, it is recommended that youeither take a copy of the base wps.cfg file and modify it to suit, or that you make sure to includethe base wps.cfg file in your customer configuration file and then override any settings youneed, 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 followingorder:a. wps.cfg in the WPS installation directoryb. My Documents/My WPS Files/.wps.cfgc. My Documents/My WPS Files/wps.cfg

d. My Documents/My WPS Files/.wpsv3.cfge. My Documents/My WPS Files/wpsv3.cfg


123

f. wps.cfg in the current directoryg. wpsv3.cfg in the current directory

4. WPS checks for the environment variable WPS_USER_CONFIG. If it exists then the specifiedconfiguration file is processed.

5. WPS checks for the environment variable WPS_OPTIONS. If it exists, then any options that arespecified in WPS_OPTIONS are processed. The syntax of this environment variable is the same as ifthe 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 Optionsconfiguration 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 below are not loaded.

2. WPS then checks the WPS_OPTIONS and WPS_V3OPTIONS environment variables for -configoptions and processes the files named by them. If any configuration files are loaded in this way, thenthe list of default configuration variables in step 4 below are not loaded.

Note: 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 step4 below are not loaded.

Note: 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.• .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 arespecified in WPS_OPTIONS are processed. The syntax of this environment variable is the same as ifthe 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.


124

There are also so-called "restricted" configuration files that will always be processed. Any optionsin these files cannot be changed by any other method. The files are based on the user's userid andgroupid. For example if the user is <user> and the group is <group> then the following configurationfiles 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 theWPS Server Explorer View open and right click on the WPS Server icon and choose Propertiesfrom the pop-up menu. In the Properties dialog, choose System Options and you will see the valuesof all system options for the server. Scrolling down to CONFIG will show all the configuration files thatwere used.

You can also set the VERBOSE system option on the command line, or in the Startup Optionsconfiguration panel for a server and WPS will generate information in the normal log output indicatingwhich 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 Optionsscreen it is possible to change the values that System Options will be set to when the Workbench isloaded. 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....4. Click the Select... button (next to the Name text box).5. Scroll down the list and find the VERBOSE option and click OK.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 the Log). The change to the VERBOSE option means that the

processed configuration files and the system options will be shown there when the Workbenchstarts.


125

AutoExec filesAutoExec files are programs that are automatically executed when WPS is started. They can be usedfor a number of purposes, such as setting up common libnames so that they do not need to be addedto every program that is run.

When using the Workbench the file will be executed when WPS is first launched and each time theserver is restarted. The Workbench also offers the chance to have code run before and/or after eachprogram. 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 onyour 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 a different file, or a file that is in a non-standard directory, then this canbe 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 OutputExplorer View or Results Explorer View open and right click on the WPS Server icon and chooseProperties from the pop-up menu.

Then, from there, select Startup Options from the dialog box that is shown, and proceed as follows:• 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.


126

• A message box will appear stating that the change will not occur until the server is restarted. ClickYes to perform the restart.

• Once the server has been restarted then the file you have specified will have been executed.

Note: If a default autoexec.sas is found and executed, then the AUTOEXEC system option willbe changed to point to that file.

Datagrid Filter ExpressionsYou can filter the contents of the datagrid when viewing a dataset. The filter menu options areessentially shortcuts to preparing a filter expression to use when the server is queried for the datasetdata.

If the observation on which the filter is based is not a date, datetime or time formatted variable, you canedit the filter expression that is generated. Choosing to filter on these variables from the menu will startthe expression, and leave the cursor ready for you to enter a value to filter by, if one is needed. Youcan then amend this filter by clicking on the expression and editing it.

Note: You cannot edit the expressions of date, datetime or time variable filters. These can onlybe cleared and re-entered.

The table below shows the editable expression syntax that is available from the filter menu.

Filter Expression Syntax

Criteria Expression Examples

Equal to EQ x or EQ s Is equal to 100 (numeric)

EQ 100

Is equal to "Garcia" (string)

EQ "Garcia"

Not equalto

NE x or NE s Is not equal to 100 (numeric)

NE 100

Is not equal to "Garcia" (string)

NE "Garcia"

Less than LT x Is less than 100

LT 100


127

Criteria Expression Examples

Greaterthan

GT x Is greater than 100

GT 100

Less thanor equal to

LE x Is less than or equal to 100

LE 100

Greaterthan or equalto

GE x Is greater than or equal to 100

GE 100

Between(inclusive)

BETWEEN x AND y Is between 100 and 200

BETWEEN 100 AND 200

Notbetween(inclusive)

NOT BETWEEN x AND y Is not between 100 and 200

BETWEEN 100 AND 200

Is missing IS MISSING IS MISSING

Is notmissing

IS NOT MISSING IS NOT MISSING

In IN(x, y) or IN(s1, s2) Is one of the values 100, 200 or 300

IN (100,200,300)

Is one of the values "Garcia", "Jones" or "Smith"

IN ("Garcia","Jones","Smith")

Startswith

LIKE "s%" Starts with the string "Gar"

LIKE "Gar%"

Ends with LIKE "%s" Ends with the string "cia"

LIKE "%cia"

Contains LIKE "%s%" Contains the string "ar"

LIKE "%ar%"


128

Welcome PagesAbout

The welcome pages display introductory information about WPS Workbench. They are designed fornew 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 areinterested 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. 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 thatare open.

• Restore: Make the welcome pages go back to a normal docked view alongside the other openwindows.

• Maximize: Expand the welcome pages to fit the entire Workbench and hide any other openwindows.


129

Reporting ProblemsGetting support

How you access technical support for your WPS software depends on how you purchased yoursoftware. 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 thatentitles you to unlimited free upgrades throughout the twelve months, and free email support [email protected]. We always respond promptly to requests for email support andwill 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 superusers through which all technical support requests are handled.

Resolutions to problems may include suggested workarounds or may require you to update your WPSsoftware installation. Due to the complex nature of the language of SAS it may require some interactionbetween World Programming and you to identify and resolve the cause of the problem.

WPS Server Log Files

For certain types of issue you may be requested to provide the log files that are produced by the WPSServer 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 willbe 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 beingused 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.

Note: Because .metadata and .log start with a period, they will normally be hidden and youwill 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 edityour preferences to show hidden and/or backup files.

mailto:[email protected]


130

Legal NoticesCopyright © 2002-2017 World Programming Limited.

All rights reserved. This information is confidential and subject to copyright. No part of this publicationmay be reproduced or transmitted in any form or by any means, electronic or mechanical, includingphotocopying, recording, or by any information storage and retrieval system.

Trademarks

WPS and World Programming are registered trademarks or trademarks of World Programming Limitedin the European Union and other countries. (r) or ® indicates a Community trademark.

SAS and all other SAS Institute Inc. product or service names are registered trademarks or trademarksof SAS Institute Inc. in the USA and other countries. ® indicates USA registration.

All other trademarks are the property of their respective owner.

General Notices

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 computerlanguage often called "the SAS language" or simply "SAS".

WPS includes software developed by third parties. More information can be found in the THANKS oracknowledgments.txt file included in the WPS installation.