workbench user guide wps workbench user guide w… · workbench user guide version 3.3 7...

Workbench user guideVersion 3.3

WPS Workbenchuser guide

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

programs”

Version: 3.3.3Copyright © 2002-2018 World Programming Limited

www.worldprogramming.com


2

Contents

Introduction...............................................................................................7About this guide............................................................................................................................. 7About WPS.....................................................................................................................................7

Eclipse..................................................................................................................................8WPS and SAS® software.............................................................................................................. 9

Getting started........................................................................................11Workspace Launcher....................................................................................................................11

Welcome pages.................................................................................................................12Migrating existing programs or projects.......................................................................................13

Migrating from previous versions of WPS.........................................................................13Migrating from SAS® software..........................................................................................13

Importing the sample and other projects..................................................................................... 14Workbench layout.........................................................................................................................14

Default WPS perspective.................................................................................................. 15Online help................................................................................................................................... 16Cheat sheets................................................................................................................................ 17

WPS components...................................................................................22

Licence key.............................................................................................24Applying a licence key................................................................................................................. 24Viewing your applied licence details............................................................................................24

WPS server............................................................................................. 26Configuring the local WPS installation.........................................................................................27Default WPS server..................................................................................................................... 28WPS server LOCALE and ENCODING settings......................................................................... 29

General text file encoding................................................................................................. 30

Workbench views...................................................................................32The Project and File Explorer views............................................................................................32

Project Explorer................................................................................................................. 33File Explorer...................................................................................................................... 35

Link Explorer................................................................................................................................ 37WPS Server Explorer...................................................................................................................40

Local WPS server properties............................................................................................ 43Remote WPS server properties........................................................................................ 45

Properties......................................................................................................................................46


3

Editor............................................................................................................................................ 47Bookmarks....................................................................................................................................47Tasks............................................................................................................................................ 48Outline (of structural elements)....................................................................................................48Output Explorer............................................................................................................................ 49Results Explorer........................................................................................................................... 50Progress........................................................................................................................................51Console (for remote server standard output)...............................................................................52Search.......................................................................................................................................... 52

Working with views............................................................................... 54View stacks.................................................................................................................................. 54Opening a view............................................................................................................................ 55Closing a view..............................................................................................................................55Moving a view.............................................................................................................................. 55Detaching and re-attaching a view.............................................................................................. 56Resizing a view............................................................................................................................ 56Minimising a view.........................................................................................................................57Maximising a view........................................................................................................................57Restoring a view.......................................................................................................................... 57Perspectives................................................................................................................................. 58

Opening a perspective...................................................................................................... 58Closing a perspective........................................................................................................59Resetting a perspective.....................................................................................................59Saving a perspective.........................................................................................................60Deleting a perspective.......................................................................................................60

Projects................................................................................................... 61Project Definition File................................................................................................................... 61Managing projects........................................................................................................................ 62

Creating a new project...................................................................................................... 62Copying a project.............................................................................................................. 68Deleting a project.............................................................................................................. 68Closing and re-opening a project......................................................................................68Importing files.................................................................................................................... 69Exporting a project............................................................................................................ 70Working with multiple projects...........................................................................................71

Switching to a different workspace.............................................................................................. 71Local history................................................................................................................................. 71

Comparing with local history............................................................................................. 72Replacing with local history...............................................................................................73Restoring from local history.............................................................................................. 74Local history preferences.................................................................................................. 74

Comparing and merging multiple files......................................................................................... 75


4

Managing files within the File Explorer...............................................77Creating a new folder in a file system.........................................................................................77Creating a new file in a file system............................................................................................. 77

Creating a new program file in a file system.................................................................... 78Opening a file in a file system.....................................................................................................79Moving a file within a file system................................................................................................ 79

Moving files using Cut and Paste..................................................................................... 79Moving files using Drag and Drop.................................................................................... 80

Copying a file within a file system...............................................................................................80Copying files using Copy and Paste.................................................................................80Copying files using Drag and Drop...................................................................................81

Renaming an object within a file system.....................................................................................81Deleting an object from a file system.......................................................................................... 82WPS File Explorer Preferences (Hidden Files)........................................................................... 82

Preferences.............................................................................................83Preferences filter.......................................................................................................................... 83General Preferences.................................................................................................................... 84Shortcut Key Preferences............................................................................................................ 86Backing up your Preferences.......................................................................................................87

Creating a new program....................................................................... 90WPS Syntax Colouring.................................................................................................................92Entering WPS code via templates............................................................................................... 93Dynamic Help for Language Elements........................................................................................ 94Using Program Content Assist.....................................................................................................94WPS Code Injection.....................................................................................................................95Code Analyser..............................................................................................................................95

Analysing program compatibility........................................................................................96Analysing language usage................................................................................................ 97Analysing mainframe programs.........................................................................................98Viewing or exporting an analysis report............................................................................99Analysis restrictions...........................................................................................................99

Working with editors........................................................................... 100SAS Editor..................................................................................................................................100Text Editor.................................................................................................................................. 101System Editor............................................................................................................................. 101In-Place Editor............................................................................................................................102Default Editor..............................................................................................................................102Text Editor Preferences............................................................................................................. 103Closing files................................................................................................................................ 103


5

Text-based editing features................................................................ 104Bookmark anchors..................................................................................................................... 105

Adding a bookmark......................................................................................................... 106Deleting a bookmark....................................................................................................... 107

Task markers..............................................................................................................................107Adding a task.................................................................................................................. 107Deleting a task................................................................................................................ 108

Jumping to a particular project location.....................................................................................108Navigation between multiple project files...................................................................................109Searching and replacing............................................................................................................ 110Undoing and redoing your edits.................................................................................................110

Libraries................................................................................................ 111Set WORK location.................................................................................................................... 112Catalogs......................................................................................................................................112Datasets......................................................................................................................................114

Importing datasets........................................................................................................... 114Opening a dataset...........................................................................................................119Exporting datasets...........................................................................................................132Clearing datasets.............................................................................................................133

Running programs............................................................................... 134WPS Preferences for running programs....................................................................................134Running a program from inside the Workbench........................................................................136

Running part of a program..............................................................................................137Stopping an execution.....................................................................................................138

WPS in Command Line mode................................................................................................... 138Running a program from the command line of a Windows platform............................... 140Running a program from the command line of a non-Windows platform........................ 141

Working with program output............................................................ 143Dataset generation..................................................................................................................... 143Managing ODS output................................................................................................................145

Result Options Preferences............................................................................................ 145Logs................................................................................................................................. 146PDF output...................................................................................................................... 149Listing output................................................................................................................... 150HTML output....................................................................................................................153Clearing the results output.............................................................................................. 154

Restarting the server..................................................................................................................155

WPS Link client/server setup............................................................. 157Managing local and remote host connections........................................................................... 158


6

Local host connection properties (Directory Shortcuts).................................................. 159Creating a new remote host connection......................................................................... 159Defining a new WPS server............................................................................................165Exporting host connection definitions to a file................................................................ 166Importing host connection definitions from a file.............................................................167Exporting WPS server definitions to a file...................................................................... 167Importing WPS server definitions from a file.................................................................. 167

Database connectivity......................................................................... 169Introduction................................................................................................................................. 169Connecting to an Oracle database............................................................................................ 170Connecting to a DB2 database..................................................................................................171Connecting to a SQL Server database......................................................................................172Connecting to a MySQL database.............................................................................................173Connecting to a database using ODBC.................................................................................... 174

Configuration files............................................................................... 177

AutoExec file........................................................................................ 181

WPS Tips and Tricks...........................................................................183

Troubleshooting................................................................................... 186

Making technical support requests................................................... 188

Legal Notices........................................................................................189


7

Introduction

About this guideThis user guide is intended to help you gain familiarity with the graphical user interface of WPS (theWorld Programming System), which allows you to create, edit and run programs written in the SASlanguage (hereafter referred to as SAS programs). This interface is referred to as WPS Workbench, or,more simply, the Workbench.

Note:The user guide also covers the running of SAS programs using WPS in Command Line mode, andvarious system administration features.

The user guide has a WPS Tips and Tricks section that provides you with links to some useful features,and a Troubleshooting section to help you resolve some problems that users have previously reported.

The user guide does not aim to:

• Train you in the use of the SAS language. If you are not already familiar with this language, there isa 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 shouldbe sufficiently familiar with the system to run some basic programs and to begin processing andanalysing data.

NotationWhenever you need to type in code, the guide displays it like this:

PROC OPTIONS;RUN;

In general, the guide uses menu options when suggesting that you need to interact with WPS, but thereare also toolbar buttons and context menu options available for many WPS options. Menu and buttonoptions are shown in a bold font, for example File ➤ New ➤ Project.

About WPSThe World Programming System (WPS) consists of two fundamental components:


8

• A GUI (Graphical User Interface)/IDE (Integrated Development Environment) known as WPSWorkbench. This environment utilises the Eclipse platform as the basic framework to provide theGUI. This GUI/IDE provides facilities to manage, create and edit programs written in the SASlanguage, and then to run these programs via the WPS server.

• A compiler/interpreter. This can be run from the command line (CLI) and is used to execute existingprograms (sometimes referred to as running WPS in batch mode). When using WPS Workbench,the compiler is run as a server process (refer to WPS server process below) and is used to processand execute programs.

WPS server processIn order to run programs written in the SAS language (refer to WPS and SAS® software), WPSWorkbench requires a connection to a WPS server process (for more information, refer to WPSserver). This process may be running either on the local workstation (a local host connection), or onan installation of WPS on a remote machine (a remote host connection). Servers running under thelocal connection are termed local servers, whilst servers running under a remote connection are termedremote servers.

WPS licence key(s)In order to be able to execute a program written in the SAS language, the WPS server componentneeds to be activated by the application of a WPS licence key (supplied separately). Refer to thesection on the Licence key.

Important:The person who installs WPS and applies the licence keys on a machine must have operating systemadministrator privileges on that machine.

EclipseEclipse 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, and so on. WPS Workbench is an example of theEclipse environment supplied with a suite of plug-ins suitable for editing SAS programs.

WPS intentionally leaves the Eclipse environment open for advanced users to plug in other third partytools and facilities for source control, Java development, C++ development, XML editing, and a varietyof other uses. Because the Eclipse platform can accommodate other plug-ins, WPS Workbench hassome features that it does not presently utilise but they are included to allow users to add other Eclipse-based plug-ins and extensions.


9

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

For more information about Eclipse and other available plug-ins, visit www.eclipse.org.

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

retrieves updates to the Eclipse platform itself, or other new or updated third party plug-ins.

WPS and SAS® softwareIf you are accustomed to using other products related to the SAS language, you will find that thelanguage support in WPS is familiar. You can expect to find much of the same syntax in terms ofprocedures, formats, macros, DATA steps, and so on.

WPS will also provide other recognisable features and objects such as logs, datasets, Work library, andso on. Other features may be new to you, such as the Workbench environment itself and the way inwhich it handles or displays objects. You will find that the Workbench has help and reference material toassist you in migrating to WPS.

Compatibility with SAS® softwareBesides being able to run, modify, share and save programs written in the SAS language, WPS is alsoable to read from and write to data files used by SAS software. WPS also includes a wide selectionof library engines to allow you to access many leading third party databases, data warehouses andHadoop big data environments.

WPS also uses a proprietary dataset file format known as WPD. As the default dataset library engine,WPD datasets are used for the Work library. Because it is the dataset library engine that is native toWPS, it has the most complete feature support, including, for example, indices.

Supported language elementsWPS does not yet support every element in the SAS language. The Workbench provides a CodeAnalyser to help determine if any of your existing SAS programs contain unknown or unsupportedlanguage elements.

Refer to the help guide entitled WPS Reference for Language Elements for details on the syntax of thelanguage elements that are supported.

http://www.eclipse.org


10

Existing SAS programsWPS uses the term SAS program, or simply program, to describe scripts, programs and applicationswritten in the SAS language. To use existing programs within WPS Workbench, refer to Migrating fromSAS® software.


11

Getting started

Workspace LauncherWPS Workbench is launched via \eclipse\workbench.exe in your WPS installation, or via theassociated shortcut.

When you first launch WPS Workbench, the Workspace Launcher is displayed, for example:

A workspace is the parent folder used to hold one or more projects. It is possible to use any folderon any drive that your computer can access, as a workspace. The workspace must have a physicallocation, which is also the default location for the newly created projects within it. However, projects canbe created in non-default locations.

Note:From version 3.1 of WPS onwards, it is no longer a requirement to use projects to manage yourWorkbench resources. This is because many files accessible through the operating system are nowavailable from within the Workbench, via the File Explorer. You can also make connections to other,remote computers in order to access files stored elsewhere (refer to the Link Explorer).

On Windows, the default location of the workspaces when WPS is first installed is your My Documentsfolder, and, on UNIX and Linux platforms, it is the directory to which your $HOME environment variableis set. In all cases, the sub-directory is called WPS Workspaces and the workspaces are namedincrementally, starting at Workspace1.


12

If you do not wish to use the workspace folder that is suggested in the Workspace field, then eitherclick the drop-down to the right of the field to select an alternative workspace, or click Browse… tobring up the Select Workspace Directory dialog (this allows you to either select an existing folder touse as a workspace, or create a new folder).

Whenever you change the line in the Workspace field of the Workspace Launcher to point at a newworkspace, then the Welcome pages are redisplayed.

Note:Unless you select Use this as the default and do not ask again, then the WorkspaceLauncher will re-appear whenever you launch another WPS Workbench session. If you doselect this option, you can always redisplay the Workspace Launcher subsequently by selectingWindow ➤ Preferences ➤ General ➤ Startup and Shutdown ➤ Workspaces ➤ Prompt forworkspace on startup.

Welcome pagesThe Welcome pages display introductory information about WPS Workbench. The default GetStarted page is designed to help you start using WPS Workbench as quickly as possible. This pagealso displays a number of links to other welcome pages, including our website.

Closing and re-opening the welcome pagesTo close the welcome pages and start using the Workbench without further guidance, click the Closebutton on the Welcome tab.

You can re-open them at any time by selecting the Help ➤ Welcome.

Other controlsLocated near the top right of the welcome pages are some navigation and size control buttons:

Navigation buttons: These behave much like the buttons on a normal web browser:

• Home: Go to the start page.

• Navigate to previous topic: Go backwards to a previously viewed topic.

• Navigate to next topic: Go forwards to a previously viewed topic.

Size control buttons: These change the size of the welcome pages within WPS Workbench:

• Minimize: Shrink the welcome pages to their minimum size. This will reveal other windows 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.


13

Migrating existing programs or projectsThis section of the guide is aimed specifically at users who have existing Projects or programscreated using either software from the SAS Institute Inc. or earlier versions of WPS, and who wish touse these existing objects with the latest version of WPS.

Migrating from previous versions of WPSWorkspaces opened with previous versions of WPS can be opened with the current version, sothere are no migration steps to be performed to use a workspace from a previous version of WPSwith the latest version. However, the first time that you open a workspace that was created using anearlier version of WPS, an Eclipse dialog is displayed asking for your confirmation that it is OK for theworkspace to be upgraded automatically. Such automatic upgrades should not cause any problems.

Existing programs do not need to be modified to work with the latest version of WPS. In addition,projects that were created with earlier versions of WPS can be opened and used by later versions ofWPS without any additional action.

Migrating from SAS® softwareIf you already have programs written in the SAS language, there is no conversion process to undertakein order to use these programs with WPS. Any file with the extension .sas is assumed to be a programthat the Workbench can open, edit and run.

Accessing your existing programsYou can access your existing programs from the File Explorer.

Alternatively, you may wish to work with projects through the Project Explorer, which allows you somebenefits, for example Restoring from local history, that are not available with the File Explorer.

For help on how to manage your existing program files, refer to The Project and File Explorer views.

Checking program compatibilityOpening programs in the Workbench causes unknown or unsupported language elements tobe displayed in red. However, before trying to execute your existing programs in WPS, it is alsorecommended that you use the Workbench Code Analyser for further verification.

Analysing programs, even hundreds of programs at a time, can take less than a few minutes 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 the File Explorer and ProjectExplorer.


14

Caution:Although it is generally very accurate, the Code Analyser is not guaranteed to be 100% accurate owingto the nature of the syntax of the SAS language.

Importing the sample and other projectsTo import an existing project into the Workbench:

1. Launch the Import wizard by selecting File ➤ Import….

You will see the first page of the Import wizard.2. Expand the tree under the General node.

3. Highlight the Existing Projects into Workspace option.

4. Click Next >.5. Select one of the following options:

• Select root directory: Use this if the project is not archived in a single file. Click Browse... toselect the folder where the project is located.

• Select archive file: Use this if the project to import is archived in a single file (as a zip, tar ortar.gz, for example). Click Browse... to select the archive file containing the project.

Note:If you wish to select the sample projects that were supplied with your version of the Workbench,browse to the doc folder within your Workbench installation, select your language folder (forexample, en, es or fr), and then select the relevant samples.zip folder.

If the file or folder you just browsed for contains a valid project, you will see it listed in the Projectssection of this panel. All projects that are initially listed are selected for import by default. Deselectany of those that you do not wish to import.

6. Click Finish to start the import process.

Workbench layoutThe layout of the Workbench can be changed according to your needs. The various layouts are knownas Perspectives, with each different perspective being specifically intended for the task of creating,managing, editing and running particular programs.


15

Default WPS perspectiveThe following is an example of the default WPS perspective used immediately following the initialinstallation of WPS Workbench:

The default WPS perspective shows all Workbench views, with the exception of Online help,Bookmarks, Tasks and Search.

Note:If you need to return to this perspective at any time, select Window ➤ Open Perspective ➤ WPS.Although you cannot delete or rename this WPS perspective, you can save your own screen layoutunder the same name.

Refer to Perspectives for details on customising this layout.


16

Online helpThe context-sensitive Help view allows you to display relevant help items automatically as youselect different Workbench views. This view is not open by default. To add this view to the currentperspective, press F1 on your keyboard, or select either Help ➤ Dynamic Help or Window ➤ ShowView ➤ Other… ➤ Help ➤ Help.

This help will update dynamically as you select different views around the interface. However, once youhave navigated away from a dynamic help page, for example by clicking the Related Topics atthe top of the Help view, then the help will no longer dynamically update as you move around the userinterface. To restore the context-sensitive help, either press F1 again or click the Related Topicslink.

If you wish to display the contents of the full WPS documentation in an Eclipse help tree view outsidethe Workbench, select Help ➤ Help Contents. You can also access this same window by selecting Show in External Window from the Help view toolbar (although selecting this option opens theEclipse help at the current Workbench topic). This external view is not context-sensitive.

Help view controlsAs you navigate by clicking on the various links and buttons in this Help view, you will see numerousdifferent controls available, for example:

• Related Topics: If this link is bold, then it indicates that the help is currently context-sensitive.If you click on any of the related links below it, then the Related Topics link is no longer bold,which indicates that you need to either press F1 or click the Related Topics link again to restorecontext-sensitivity.

• Show in Contents: This will synchronise the help topic you are looking at with its position in thecontents tree view.

• 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 the help for specific keywords and phrases.

List of key bindingsIf you wish to view the list of key bindings (that is to say, current keyboard shortcuts), either selectHelp ➤ Key Assist or press Ctrl + Shift + L.

To display the Preferences page on which you can change the key bindings, or add new ones, you canthen either press Ctrl + Shift + L again, or select Window ➤ Preferences ➤ General ➤ Keys. Refer toShortcut Key Preferences.


17

Cheat sheetsThe Workbench is supplied with tutorials known as cheat sheets. They are designed to help you startusing WPS by introducing you to specific tasks and features. A cheat sheet is laid out as a sequenceof steps for you to undertake. As you progress from one step to the next, the cheat sheet has a Help button that you can select to display a related help topic that discusses or guides you through thatparticular step.

Cheat sheet typesCheat 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 that follow on, as shown below:

These cheat sheets appear as a simple list in the Workbench user interface.

A composite cheat sheet is really just a collection of simple cheat sheets. They break down a largecomplicated topic, made up of many tasks, into smaller manageable groups. Each of these groups hasits own introduction and conclusion, as shown below:

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


18

Note:By default, the groups pane is above the tasks, although maximising the view will move it to the left.

Launching a cheat sheetCheat sheets can be launched either from the welcome pages or from the Workbench main menu.

Launching a cheat sheet from the welcome pages:

1. Open the welcome pages by selecting Help ➤ Welcome.

2. Select the Tutorials page.


19

3. From the list of available cheat sheets, click on the one you wish to open.

Launching a cheat sheet from the Workbench Menu:

1. From the main menu, select Help ➤ Cheat Sheets....

2. From the list of available cheat sheets, double-click on the one you wish to open.

Cheat sheet quick toolbarIf you launch a cheat sheet from the Workbench menu (as opposed to from the welcome pages), atoolbar is displayed specifically for use with the cheat sheet:

• 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 there is already an active cheat sheet, itscompletion status is automatically saved and then the newly selected cheat sheet is opened. Onlyone cheat sheet may be open at any one time.

• Minimize the cheat sheet view.

• Maximize the cheat sheet view.

• This button is in the tab of the cheat sheet view, and, as well as closing the view, it saves thestatus of the active cheat sheet so that your position is not lost.

Working through a cheat sheetEach cheat sheet has a sequence of steps that always begins with an introductory step. When youlaunch a new cheat sheet, the introductory step is expanded so that you can read a brief descriptionabout the selected cheat sheet.

To start working with a simple cheat sheet, select Click to Begin at the bottom of the introductorystep. The next step is then expanded and highlighted. You should also see action buttons at the bottomof the next step, for example Click to Complete. You can now progress through each step in thecheat sheet.

To start working with a composite cheat sheet, read the introduction and then click the Go to... linkat the bottom of the first sheet. The introduction for the first group of tasks will be displayed, and youcan then click on the Start working... link to begin. From this point on, the task group behaves verymuch as a simple cheat sheet.

Completing a cheat sheetWith simple cheat sheets, when you have finished working with a particular step, you should selectClick when complete to move to the next step. The next step is automatically highlighted and itbecomes the active step. A check mark appears in the left margin of each completed step.


20

Composite cheat sheets behave in much the same way, until you complete all the sheets in thecurrent group. 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 take youto the introduction for the next group.

Getting Related Help informationTo obtain detailed instructions or related information for a particular step, select the Open RelatedHelp icon in the upper right hand corner of that step. The Related Help will open in a separate Helpwindow.

Open any stepYou can open any step out of sequence, regardless of whether it is marked as completed, by simplyselecting it via its icon.

Note:Any step opened in this way will not change from its complete or incomplete state, and steps followingthe active step do not have a Click to Complete icon.

Click Collapse All Items but Current at the top of the cheat sheet view to collapse back to just thecurrent 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 a cheat sheetAt 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 (for example, programs, projects, and so on) that you have already created, are not deletedwhen you restart a cheat sheet.

Composite cheat sheets allow you reset task groups. Right-click on the task group in the groups pane,then select Reset from the menu. You will then see a confirmation dialog. Click OK and the introductionfor the group is then shown in the task pane.

Completing a cheat sheetWith 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.


21

Composite cheat sheets are considered complete when all task groups have been completed. Ifthis is the case, then all groups will have a check mark next to them in the groups pane. You maythen restart all the task groups if you wish, by right-clicking the top level item in the groups pane andselecting Restart all tasks.

Closing a cheat sheetYou 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.


22

WPS componentsThis section gives brief descriptions of the objects managed by the Workbench.

ProjectsThese consitute the fundamental unit of organisation. You would typically put related programstogether in a project. For example, you might have a project for applications under development,another for monthly reporting jobs, and so on.

ProgramsYou can create and modify programs, that is to say files with the extension of either .sas or .wps,using the SAS Editor (refer to Creating a new program for an example). This editor uses colourcoding to highlight different language elements as well as syntax errors.

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

Listing outputThis contains the printed output from any programs that you have run. For example, this couldbe a table of data generated by a PROC PRINT statement in a program. Listing output can beviewed, printed and saved from within the Workbench. The listing output generated by the WPSserver is cumulative and contains the output from each program that has been run since theWorkbench was launched, the WPS server was last restarted, or the listing was last cleared.

HTML outputThese are the physical HTML files that a program may generate. For example, they could be aseries of HTML files that show the results of analysing some data, and that have been generatedas a result of an ODS HTML statement in a program. HTML output can be opened and viewedwithin the Workbench.

ODS output (refer to Managing ODS output)As described, the ODS (Output Delivery System) can be used to produce text listing and HTMLoutput. Each program can specify when and where its output is stored but it is also possibleto allow the Workbench to manage the process automatically. The default option is for theWorkbench to generate HTML output for viewing via the Output Explorer.

LibrariesThese hold the temporary files, datasets, catalogs, and so on, that are created as a result ofrunning a program.

Filerefs (refer to WPS Server Explorer)These hold the individual references to files, whether automatically generated or defined via theFILENAME statement.


23

DatasetsThe data generated from running a program is stored in datasets. You can either browse or edit adataset using the dataset viewer.

Host ConnectionThis refers to a computer, local or remote, to which the Workbench has access. The creation ofa host connection is the first step of a two-step operation to create a remote link inside WPS: youfirst create a connection to the remote host; and then add a WPS server to this remote host sothat you can run your programs remotely (refer to Managing local and remote host connections).

WPS serverThis is the engine responsible for executing programs and generating the resulting output, suchas the log, listing output, HTML results files, and datasets. A WPS server is associated with aparticular host connection. The WPS server also maintains an environment of assigned libraries,Filerefs, defined macros and macro variables, and so on, with which all of the running programsinteract.

Directory ShortcutA Directory Shortcut is a shortcut to a path on the host's file system that can be accessed viathe File Explorer (refer as appropriate to Local host connection properties (Directory Shortcuts)or, for a remote host, Directory Shortcuts). You can create new directory shortcuts via therelevant host connection's Properties in the Link Explorer, or by right-clicking on the requiredfolder(s) in the File Explorer and selecting New ➤ Directory Shortcut.


24

Licence keyWPS requires a valid licence key in order to run programs on a WPS server. A licence key isprovided in a file ending in .wpskey that is separate from the WPS installation file.

Note:If you are using WPS Link (refer to the Link Explorer), and wish to restrict the execution of programs tothe linked server, then you only need a licence key for the server installation of WPS. However, if youwish to be able to execute programs on either the client machine or the linked server, then you needseparate licence keys for the server and the client installations of WPS.

Applying a licence keyTo apply a new licence key to your WPS installation.

Attention:If you are using a Microsoft Windows operating system, then, before applying a licence key, ensure thatyou have administrator privileges on your computer.

1. Select Help ➤ Apply Licence from the Workbench menu.

2. In the resultant dialog Import licence for server Local Server (or substitute the name of yourremote WPS server in place of Local Server), do one of the following:

• Copy and paste the entire contents of your licence file into the window.• Click Import from file.... Locate your licence key file and then click Open. You should see the

contents of the licence key file displayed in the window.3. Click Finish to apply the licence.

If you wish to apply the licence key on a Unix-based platform, then enter the following:

wps_install_root/bin/wps -stdio -setinit <license.wpskey

wps_install_root is the directory where WPS is installed.

Viewing your applied licence detailsTo view the details of the licence key that has been applied to your WPS installation:

1. Open the Licence Key information window by selecting Help ➤ View Licence from theWorkbench menu.


25

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


26

WPS serverIn order to run programs, the Workbench requires a connection to a licensed WPS server. The termserver here is used to refer to a server process. The process may be running on the local workstation(as a local host connection - refer to Local host connection properties (Directory Shortcuts)), or it maybe running on an installation of WPS on a remote machine (as a remote host connection - refer toRemote host connection properties).

Servers running under the local connection are termed local servers. Servers running under a remoteconnection are termed remote servers.

With a typical workstation installation of WPS there will be a single host connection called Local and aserver called Local Server. This server will be started by default when the Workbench is started, andterminate when the Workbench is closed down. Further local servers can be created if required or thelocal server can be deleted or uninstalled (refer to Configuring the local WPS installation).

Note:If you are using a non-Windows platform, and wish to run programs on a remote server only, thenyou can go into the Link Explorer in WPS Workbench and either Stop or Delete the Local Server,without your licence being affected. However, deleting all local servers, where there are no remoteservers, will render users unable 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.

Setting up remote servers gives you the ease of use of the Workbench at your local workstation, whilealso giving you access to the processing power of remote server machines. Multiple servers can rununder a single remote host connection. Creating a link to a remote host, so that you can run yourprograms remotely, is a two-step operation:

1. Create a connection to the host by following the steps in Creating a new remote host connection.2. Define a server on this host by following the steps in Defining a new WPS server.

Once a connection to a remote machine has been authenticated, one or more WPS servers can bestarted without the need for further user authentication. Multiple users can have remote connectionsconfigured to the same machine, with the only restriction being the resources on that machine.

The list of defined connections and servers is stored within the workspace, and is maintained via theLink Explorer. Therefore, changing your workspace will potentially load a list of different connectionsand servers. When you create a new workspace, then, by default, there is a single host connectioncalled Local and a single server called Local Server.


27

For user convenience when moving between workspaces, or to share server definitions within a workgroup, server definitions can be exported to an external file (see Exporting WPS server definitions toa file) and imported from a file previously created in such a way (see Importing WPS server definitionsfrom a file).

Configuring the local WPS installationBecause it is not mandatory to use the WPS server component on the local host if programs are notbeing executed on it (in that they are being run only on a remote linked server), you can isolate theWPS Local Server from the installation as described below.

Note:You can only do this on a workstation that is running on Windows.

• If you have not already installed WPS, then run the relevant wps msi, and, when the followingCustom Setup screen is displayed, deselect WPS Local Server, as shown below, before going onto click Next:

• If you have already installed WPS, then select WPS from the Programs and Features within theWindows Control Panel, click Change at the top of the window, followed by Change again in thefollowing window:


28

You will then come to the Custom Setup shown previously and can deselect WPS Local Server asshown, before completing the amended installation.

Caution:You should be aware that, if you uninstall WPS Local Server from a machine, your WPS installationwill no longer be licensed on that machine.

Note:If you are using a non-Windows platform, and wish to run programs on a remote server only, thenyou can go into Link Explorer and either Stop or Delete the Local Server, without your licence beingaffected.

Default WPS serverOne of the defined servers is always set as the default server. This is the server that is selected bydefault when you click on any of the following toolbar icons, or their associated keyboard shortcuts: Run, Stop, Clear Log, Clear Results and Restart Server.

Proceed as follows to set the default server.

1. Go to the WPS Server Explorer, Link Explorer, Output Explorer or Results Explorer, and right-clickon the server that you wish to be the default.

2. From the context menu, select Set as Default Server.


29

Note:If this option is not enabled, then the selected server is already the default server, or you haveselected more than one server.

The selected server is now the default WPS server, and, to denote this, it appears first in the list ofservers and is shown in bold.

WPS server LOCALE and ENCODINGsettingsThe locale used by WPS is set individually by the particular server. Proceed as follows to set thelanguage system option for the locale that you wish to use for a server:

1. In the WPS Server Explorer, Link Explorer, Output Explorer or Results Explorer,ensure that the server is running.

2. Right-click on the server and select Properties from the context menu.3. In the left hand menu of the Properties dialog, select Startup ➤ System Options.

4. On the right of the window, click Add... to display the Startup Option dialog.5. Click Select... on the right of dialog to see a list of available options in a Select Startup Option

window.6. Search for and/or scroll down to the LOCALE option, and then double-click on it. The Startup Option

dialog then displays your choice.7. Enter the required value into the Value text box, and then click OK.

Note:A list of valid LOCALE values can be found in the separate guide entitled WPS Reference forLanguage Elements, in the LOCALE Values section.

8. Click OK on the Properties dialog and you will be prompted to restart the server to apply yourchanges.

Note:Any LOCALE option defined in any external Configuration files will be ignored. You must set LOCALEas a Workbench startup option, as described above, in order for it to be used from inside the graphicaluser interface. However, when using WPS in Command Line mode to run programs in batch mode,then the startup option is ignored and the LOCALE option in the external configuration file is usedinstead.

In order to display and save programs and other files that contain characters for your selected LOCALE,you may need to set a General text file encoding value for the Workbench.


30

You may also need to set an appropriate ENCODING value on the server (for example to execute aWPS installation containing non-ASCII characters). As an example, proceed as follows to set UTF-8 onthe server:

1. Repeat steps 1-5 as above.2. Scroll down and double-click on the ENCODING option, which will be displayed in the Startup Option

dialog.3. Enter UTF8 or UTF-8 into the Value text box, and then click OK.4. Restart the server when prompted.

Note:A list of valid ENCODING values can be found in the separate guide entitled WPS Reference forLanguage Elements, in the ENCODING Values section.

General text file encodingIn order to display and save programs and files that contain international characters, you may need toset an appropriate text file encoding value. This can be done at either a global or project level.

Setting encoding at a global levelTo set an encoding value at a global level to be used by all projects and associated files:

1. Select Window ➤ Preferences.

2. In the left hand menu of the Preferences window, expand the General ➤ Workspace node.

3. In the bottom left of the Workspace panel, the controls for setting the Text File Encoding value aredisplayed.

4. Enable the Other option for Text File Encoding and select the required value from the drop-downlist of available values.

5. Click OK to apply your change.

Note:You can type in the required encoding in the Other field if you do not see the required option in thedrop-down list. If your selection is valid, it is saved when you click OK.

It is recommended that, in all cases, you check that the locale is set for your country so that datais handled correctly by the WPS server. To do this, ensure that the server is started and that thelocale displayed in the bottom right hand corner of the Workbench is set appropriately (for example,to FRENCH_FRANCE or FR_FR if you are in French territories). If it is not, proceed as in WPS serverLOCALE and ENCODING settings.


31

Setting encoding at a project levelTo set an encoding value only for programs contained in a specific project:

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

2. Highlight the desired project.

3. Select File ➤ Properties.

4. On the left of the Properties window, ensure the Resource option is selected.5. In the bottom left of the Resource panel, the controls for setting the Text File Encoding value are

displayed. The default option selected is Inherited from container(x), where (x) is the value set ata global level as described above. If you wish to change this, enable the Other option for Text FileEncoding and select the required value from the drop-down list of available values.

6. Click OK to apply your change.


32

Workbench viewsThe layout of the items in WPS Workbench is known as a perspective (refer to Perspectives) andcomprises individual windows that can contain one or more views. These views display specifictypes of information and provide specific functions. Some views also have context-specific toolbarslocated in the top right of each view.

This section gives an overview of each of the views that is available for selection (other than the Onlinehelp, which has already been covered) and describes the main actions that are carried out within eachview.

Note:Views are usually selected via Window ➤ Show View. However, where a view has not been previouslyselected, you may need to locate it initially under Window ➤ Show View ➤ Other....

The Project and File Explorer viewsBoth the Project Explorer and File Explorer views allow you to edit and manage files and foldersin a tree structure within the Workbench:


33

The Project Explorer is ideal where you have a set of files that you need to manage in one organisedworkspace. You can create several Projects in a workspace to tackle different specific tasks. Anykind of local file can be contained in a workspace, and all the operations you would expect to be ableto perform on files are available (including the ability to run programs). Objects within projects can bemanaged with Local history, and they can also be exported to archives or to other folders in the localfile system. Such archives can also be imported into this view.

The File Explorer differs from the Project Explorer in that it permits access to all files that areavailable on your local file system, and on any file systems made available by any remote hosts. It alsomakes use of Directory Shortcuts which can point to folders at any level within the file system onwhich they are created (refer as appropriate to Local host connection properties (Directory Shortcuts)or, for a remote host, Directory Shortcuts).

Note: Local history is not available when using File Explorer, and neither is Import nor Export, but

files and folders can be moved between file systems by using copy/cut/paste.

The differences can be summarised in the following table showing the availability of the various fileoperations in both views:

Option Project Explorer File Explorer

Open and Edit Yes YesFile Management Yes YesRun Programs Yes YesLocal History Yes NoImport and Export Projects and Archives Yes NoManage Remote File Systems No YesManage Full Local File System No Yes

A program can be run from either the Project Explorer and File Explorer by selecting it, right-clicking,and selecting Run On from the context menu. The menu will then expand to show the list of serverson which the program can be executed. Choosing a server will then run the program on that server. Formore information, and alternative ways of running programs, refer to Running a program from inside theWorkbench.

Project Explorer

To display this viewTo add this view to the current perspective, select Window ➤ Show View ➤ Project Explorer.


34

The files and folders displayedThe main file and folder objects displayed are as follows:

• Open projects

• Closed projects

• Folders

• Programs (that is to say, any file with the extension .sas or .wps)

• Other files (text or unknown file extensions)

Any type of file can be added to a project and listed by the Project Explorer. If your computer systemrecognises the file type, then the appropriate icon is displayed.

Note:The Project Explorer only displays projects that are in your current workspace.

Operating system toolsAs well as the Workbench's tools, you can use those supplied by your operating system to delete, cut,copy and paste objects into a project.

You may need to refresh the Project Explorer to ensure that objects manipulated in this way aredisplayed correctly (right-click on the project and, from the context menu, select Refresh).

Note:If you do use the operating system tools instead of those in the Workbench, you will not have thebenefits provided by Local history.

PropertiesSelecting an item in the Project Explorer displays information about that item in the Propertiesview.

The following Properties are shown for shortcuts, files and folders:

• Modified date & time.• The Linked field, which is True if the currently selected file is linked to a file in the associated file

system.• Name of the item.• Size of files (directory sizes are not shown)• Path details


35

File Explorer

To display this viewTo add this view to the current perspective, select Window ➤ Show View ➤ File Explorer.

File Explorer objectsThe main file and folder objects displayed by the File Explorer are as follows:

• Connections: The root node that represents a connection to a host machine. This can be eitherlocal or remote.

• Shortcuts: A directory on a file system selected for management via the File Explorer.

• Folder: A sub-folder.

• Programs: Any file with the extension .sas or .wps.

• Other Files: Text or unknown file extensions.

• Symbolic linked file: A file that points to another file in the host file system via a symbolic link.

• Symbolic linked directory: A file that points to another directory in the host file system via asymbolic 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 shortcutsIt is only possible to view files on remote systems when you have an open host connection. Suchconnections can be opened from Link Explorer, and connections are also opened when starting WPSservers in the WPS Server Explorer. When a host connection is opened, then the Connection willappear in the File Explorer. Closing a connection will then remove its node from the same view.

Each host connection is configured to have several Directory Shortcuts displayed below theconnection in the File Explorer. These permit access to the files and folders on the associated filesystem (refer as appropriate to Local host connection properties (Directory Shortcuts) or, for a remotehost, Directory Shortcuts).


36

Tip:To create a new directory shortcut in the File Explorer, right-click on the required folder, selectNew ➤ Directory Shortcut, and then supply the required shortcut name in the Directory Name field ofthe Directory Shortcut dialog.

Host connections expand into the associated Directory Shortcuts in the File Explorer. Invalidshortcuts are shown with an Invalid Shortcut icon. This means that the path configured for theseshortcuts is not available on the file system for that connection.

PropertiesSelecting an item (other than a connection) in the File Explorer displays information about that itemin the Properties view.

Note:The properties differ depending on whether you are using local or remote connections.

The following Properties are shown for shortcuts, files and folders:

• Modified date & time.• Name of the item.• Size of files (directory sizes are not shown)• Path details• The Is Link field, which is Yes if the currently selected item is a symbolic link.• Link details (if the item is a symbolic link, such as the link path).

On a remote host, the following properties are also available.

• Accessed date and time.• Group and user IDs.• Permissions

Working with files and foldersIt is possible to perform the following operations on files and folders within the File Explorer:

• New: Create a new directory shortcut, directory or file.• Cut: Selected files and directories will be moved if the user uses Paste.

• Copy: Selected files and directories will be copied if the user uses Paste.

• Paste: Performs a Copy or Cut operation.

• Delete: Deletes all selected files and directories.

• Run On: Runs selected programs on a WPS server.

• Refresh: Refreshes the currently selected node.


37

• Rename: Renames the currently selected file or directory.• Analyse: Analyses the contents of programs, and folders containing programs (refer to Code

Analyser).

These options are available from the context menu within the File Explorer. With the exception ofAnalyse, they are also available from the main menu.

ProgressProgress of the current File Explorer operation can be seen in the Progress view.

Link ExplorerThe Link Explorer allows you to manage host connections, and also any WPS servers on thoseconnections.

This is the key view if you are using WPS Link (which is the collective term for the technology usedto provide a client/server facility - refer to WPS Link client/server setup). Using WPS Workbench onyour local PC (the client), you can connect to a remote server on which WPS is installed, in order to runprograms written in the SAS language, on that remote server. The process has two stages:

1. Creating a new remote host connection.2. Defining a new WPS server.

The output from the remote server can then be viewed and manipulated from inside WPS Workbench,just as if the work had been executed locally - for example, datasets and Filerefs through the WPSServer Explorer, the log and other results through the Output Explorer, and links to the resultsthrough the Results Explorer.

To display this viewTo add this view to the current perspective, select Window ➤ Show View ➤ Link Explorer.

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


38

Managing the connections and serversIf you right-click on an open connection, the following options are displayed:

With regard to the above options:

• If you select Close Connection, then you will also stop the server(s) running on it. You can theneither select Open Connection to re-open it, or simply restart the server(s).

• For details on Export Host Connection, refer to Exporting host connection definitions to a file.• To define a New WPS Server, proceed as in Defining a new WPS server.• For Import WPS Server Definition, refer to Importing WPS server definitions from a file.

Tip:Servers can also be imported by dragging Server Definition Files (with the suffix *.sdx) onto a HostConnection node in the Link Explorer.

If you right-click on a server that is running, the following options are displayed:


39

With regard to the above options:

• If you select Stop, then the server will cease to run any program(s), but the connection will remainopen. You will need to select Start to relaunch the server (which will also restart the connectionautomatically).

• For details on Restart, refer to Restarting the server and Restarting with Advanced Server Actions.• For Set as Default Server, refer to Default WPS server.• For Export WPS Server Definition, refer to Exporting WPS server definitions to a file.

PropertiesRight-click on a connection or server in the Link Explorer, and, from the context menu, select theProperties option (if enabled), to gain access to the following:

Host Connection properties, consisting of:

• Directory Shortcuts: Refer as appropriate to Local host connection properties (Directory Shortcuts)or, for a remote host, Directory Shortcuts.

• Remote Connection Options

WPS server properties - refer as appropriate to Local WPS server properties or Remote WPSserver properties.

Tip:You can also view properties about a server in the Properties view.

The server properties include the server version, and the following information about the licence: ExpiryDATE, Grace Period, Licensed Operating System, and Licence Number.


40

Commands (in the top right hand corner of the window)• Collapse All: Collapse the view to show just the root nodes.

• Create a new remote host connection: Add a new remote connection. Refer to Creating a newremote host connection.

• Import a host connection definition: Import a connection definition file. For further informationon importing connections, refer to Importing host connection definitions from a file.

Tip:Host connections can also be imported by dragging Connection Definition Files (with the suffix*.cdx) onto the Link Explorer view.

Dragging and dropping a WPS serverA WPS server can be dragged and dropped onto a different host connection. A simple drag and dropoperation on a WPS server will move the server from its current host connection to the target hostconnection. Holding down the Control key while dragging will copy the WPS server. To maintain uniquenames, the copied server will be renamed automatically. You can rename the server manually by right-clicking the server and selecting Rename from the context menu.

WPS Server ExplorerFor each active server, the following are displayed in, and, can be opened from, the WPS ServerExplorer: all Filerefs, libraries, catalogs and datasets that have been generated as a result of runningprograms on that server, for example:


41

Note:While the Workbench is open, the Filerefs and library contents from previous runs are preserved. Inorder to clear the state of a server, you need to restart the server (as described in Restarting theserver).

To display this viewTo add this view to the current perspective, select Window ➤ Show View ➤ WPS Server Explorer.

Objects displayedAssuming that you have run one or more programs, you should see the following hierarchy displayedfor each server:

• WPS Server node: The root node that represents the WPS installation where you are runningyour programs, whether this is on a local or remote host. And then, under this node:

‣ Libraries: A parent node for individual library items.

‣ Library: A collection of catalogs and/or datasets. Refer to Libraries.


42

Note:You may also see a library node called Work. This represents the default temporary libraryused if one is not specified in a program. If you use the LIBNAME statement in a program tospecify your own library name, then you will see a library node with the specified name also listedin the view.

‣ Catalog: A collection of user-defined items such as formats and informats.

‣ Dataset: A data file containing numeric and/or character fields.

‣ Dataset View: A dataset that is created by invoking a view in the source data. For detailsabout listing and opening datasets, refer to Working with the Dataset Viewer.

‣ Numeric Dataset Field: A dataset field that contains numeric values.

‣ Character Dataset Field: A dataset field that contains character values.

‣ Filerefs: The parent node for Fileref items.

‣ Fileref: An individual reference to a file.

Although Filerefs are generated automatically, you can also create them yourself by usingthe FILENAME statement, for example:

filename shops 'c:\Users\fred\Desktop\4.1-Shops.xls';

will allow you to reference the above pathname without repeating it in full. For example, you coulduse the reference in a DATA statement to read data from c:\Users\fred\Desktop\4.1-Shops.xls, as in:

DATA shops; INFILE shops DLM = ',' DSD MISSOVER; LENGTH ShopName $20.; INFORMAT Opened DDMMYY10.; INPUT ShopName Opened FirstYear SecondYear ThirdYear FourthYear FifthYear;

Note:The link between a Fileref and its associated external file lasts only for the duration of the currentWPS session, or until you change it or discontinue it by using another FILENAME statement. Ifyou wish to keep a Fileref from session to session, then save the FILENAME statement withinthe relevant program(s). To view the details for a particular Fileref, right-click on it in and selectProperties.

PropertiesIf you select any item in the WPS Server Explorer view, other than the Libraries and Filerefsnodes, you will see information about that item displayed in the Properties view.

You can also display more detailed properties about certain items by right-clicking on an item, and,from the context menu, selecting the Properties option if it is enabled (that is to say, if there areproperties available for the selected item). The following are examples of what you might see:

WPS Server Properties


43

Refer as appropriate to Local WPS server properties or Remote WPS server properties.

Library Properties

• General: The access details (for example, Read-only or Temporary), together with the name,engine and location details.

• Members: A table of information about the members of the catalog, showing the member name andmember type for each.

Catalog Properties

• Entries: A table of information about the entries in the catalog, showing the entry name, entry typeand description for each.

• General: Name of the catalog.

Catalog Entry Properties

• General: Name, type, description, creation and modification time of the entry.

Dataset and Dataset View Properties

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

and informat.

Local WPS server propertiesThe following properties and information are available for a local server:

Note:Some items are only available when the server is running, and, where this is the case, it is noted.

Code SubmissionIf, before any program is submitted to the server, you require the working directory on the serverto be set to be the same as the directory from which the program is opened, select the optionshown here (Set the server working directory to program directory on submission). Thissetting of the working directory should then happen automatically provided that the directories areon the same host. If the directories are not on the same host, then the working directory on theserver is set to be the Initial current directory for server process specified in Startup (seebelow).If the option Set the server working directory to program directory on submission is notselected, then no changes are made to the working directory when a program is submitted to theserver.

EnvironmentThis section lists details of the server's environment (working directory, process ID andenvironment variables). This information cannot be modified, and is only available when theserver is running.


44

Macro VariablesThis section lists the automatic and global macro variables used by the server, and theassociated values. This information cannot be modified, and is only available when the server isrunning. However, you can click Add... to create new variables.

System OptionsThis lists the names of all the system options that are currently set on the server, along with theirvalues. This is the same information as would by provided via the PROC OPTIONS statement.The information cannot be modified, and is only available when the server is running.

WPS Licence InformationThis page shows the setinit information for the server, such as the products that are licensed,the amount of grace or warning time on the licence, and the date on which the licence expires.This information cannot be modified, is only available when the server is running.

WPS Software InformationThis page shows details about the WPS software, including the version number and theoperating system on which it is running. This information cannot be modified, and is onlyavailable when the server is running.

StartupThe main page has a flag called Start the server automatically on connection startup. Ensurethat this is selected if you wish the server to be started automatically whenever the associatedconnection is launched. The Initial current directory for server process entry is where youspecify the working directory for the server, determining where the output is generated. If youhave %INCLUDE statements in your code with relative paths in them, then it is important that youstart the server in the correct directory to allow those %INCLUDE statements to find the files theyare including.

The Startup page has two further sub-pages:

• System Options. When the server is running, this page allows you to specify any WPSoptions that you would like to pass to the server to process on startup, for example WPSserver LOCALE and ENCODING settings, and other options that you can pass to WPS inCommand Line mode. If you click Add... you will see a new popup dialog that allows you toclick 'Select...' to choose an option that is to be set. After choosing the option, you can set theassociated Value, before clicking OK to make the option and value active. You can then usethe Edit... and Remove buttons to modify and delete any options and values that you havepreviously created.

• Environment Variables. This page allows you to specify any environment variables that youwould like to be set before the server is started. By clicking New..., you can specify the nameof the variable and the value to which it is to be set. The item will then appear in the list. Youcan then use the Edit... and Remove buttons to modify and delete any environment variablesthat you have previously created.


45

Remote WPS server propertiesThe following properties and information are available for a remote server:

Note:Some items are only available when the server is running, and, where this is the case, it is noted.

Code SubmissionIf, before any program is submitted to the server, you require the working directory on the serverto be set to be the same as the directory from which the program is opened, select the optionshown here (Set the server working directory to program directory on submission). Thissetting of the working directory should then happen automatically provided that the directories areon the same host. If the directories are not on the same host, then the working directory on theserver is set to be the Initial current directory for server process specified in Startup (seebelow).If the option Set the server working directory to program directory on submission is notselected, then no changes are made to the working directory when a program is submitted to theserver.

EnvironmentThis section lists details of the server's environment (working directory, process ID andenvironment variables). This information cannot be modified, and is only available when theserver is running.

Macro VariablesThis section lists the automatic and global macro variables used by the server, and theassociated values. This information cannot be modified, and is only available when the server isrunning. However, you can click Add... to create new variables.

System OptionsThis lists the names of all the system options that are currently set on the server, along with theirvalues. This is the same information as would by provided via the PROC OPTIONS statement.The information cannot be modified, and is only available when the server is running.

WPS Licence InformationThis page shows the setinit information for the server, such as the products that are licensed,the amount of grace or warning time on the licence, and the date on which the licence expires.This information cannot be modified, is only available when the server is running.

WPS Software InformationThis page shows details about the WPS software, including the version number and theoperating system on which it is running. This information cannot be modified, and is onlyavailable when the server is running.

WPS Software Install LocationThis page shows the location of the remote WPS installation specified during server setup (referto Defining a new WPS server).


46

StartupThe main page has a flag called Start the server automatically on connection startup. Ensurethat this is selected if you wish the server is to be started automatically whenever the associatedconnection is launched. The Initial current directory for server process entry is where youspecify the working directory for the server, determining where the output is generated. If youhave %INCLUDE statements in your code with relative paths in them, then it is important that youstart the server in the correct directory to allow those %INCLUDE statements to find the files theyare including.

The Startup page has one further sub-page:

• System Options. When the server is running, this page allows you to specify any WPSoptions that you would like to pass to the server to process on startup, for example WPSserver LOCALE and ENCODING settings, and other options that you can pass to WPS inCommand Line mode. If you click Add..., you will see a new popup dialog that allows you toclick 'Select...' to choose an option that is to be set. After choosing the option, you can set theassociated Value, before clicking OK to make the option and value active. You can then usethe Edit... and Remove buttons to modify and delete any options and values that you havepreviously created.

PropertiesYou 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 display this viewTo add this view to the current perspective, select Window ➤ Show View ➤ Properties.

Views that interact with the Properties viewIf 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

• WPS Server Explorer

• Search

• File Explorer

• Link Explorer

Note:Not all objects in the views listed above have viewable properties - for example, you cannot viewproperties for a host connection in the Properties view.


47

EditorWhen you open any type of file in the Workbench, for example programs, logs, output, datasets, textfiles, and so on, it is opened as a tab in the Editor. This view is always available and cannot be closed,and for this reason it is not listed under Window ➤ Show View. However, you can close individual filesthat are open in the Editor.

It is possible to split the Editor so that you can view and/or modify two or more files at once, byselecting Window ➤ Editor ➤ Toggle Split Editor (Horizontal) or Window ➤ Editor ➤ ToggleSplit Editor (Vertical). You can also open another copy of the current file by selectingWindow ➤ Editor ➤ Clone.

To create a new program within the Editor, refer to Creating a new program. You should also refer tothe Text-based editing features that can be used within the Editor.

Whether or not you can edit a file once it has been opened depends on its type, for example:

• You cannot edit logs and output files opened from the Output Explorer.• You can edit a dataset that has been opened from the WPS Server Explorer, once you have

switched to Edit mode (refer to Editing a dataset).• Files opened from the Project Explorer can normally be edited. You can even select which editor to

use when opening the file (as discussed in Working with editors).• You can also open files for editing from the File Explorer.

BookmarksYou can add bookmarks on any line inside a program, or indeed inside any file that you can openand edit with the Workbench via the Project Explorer. To list and navigate between your bookmarks,you can use the Bookmarks view. Refer also to Bookmark anchors .

Note:This view lists all bookmarks regardless of whether or not the associated programs are open. It doesnot list bookmarks from programs in a closed project. It is not possible to create bookmarks on filesopened from the File Explorer, unless they are members of a project . This is because files openedoutside of Projects may be located anywhere in a file system on a local or remote host, and bookmarkscan only be set on files that are members of a workspace project.

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

To display a bookmark listed in the view


48

Either double-click on the required task, or right-click on it, and, from the context menu, select GoTo. The relevant file will then be opened (if it was closed), and the bookmarked line will be highlighted(or else the first line in the file if the entire file was bookmarked).

TasksYou can add Task markers (reminders) against any line in a program that has been opened from theProject Explorer, and associate each of them with notes and a priority level. To list, update and navigatebetween any tasks you have added, you need to use the Tasks view.

Note:The Tasks view lists tasks regardless of whether or not the programs are open. It does not list thosefrom programs in a closed project. It is not possible to create tasks on programs opened from the

File Explorer, unless they are members of a project. This is because programs opened in thisway may be located anywhere in a file system, and tasks can only be set on files that are members of aworkspace project.

To display this viewTo add this view to the current perspective, select Window ➤ Show View ➤ Other… ➤ General ➤ Tasks.

This view allows you to change the priority levels of tasks, modify the descriptions, and either markthem as completed or leave them uncompleted.

To display a task listed in the view

Either double-click on the required task, or right-click on it, and, from the context menu, select Go To. The relevant file will then be opened (if it was closed), and the line containing the task will behighlighted.

Outline (of structural elements)To assist in navigating programs, logs, listing or HTML output, the Workbench displays structuralelements from these items in the Outline view. If you click on a structural element in this view, therelevant line in the file will be highlighted.

Opening or giving focus to a program, log, listing or HTML result file, automatically refreshes theOutline view to display the structural elements that are relevant to the active item.

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


49

Program structural elementsOpening programs causes the Outline view to display the following structural elements:

• Global statement

• DATA step

• Procedure

• Macro

You can control which structural elements are displayed in the program's Outline view. In the toolbarat the top of this view you will see buttons with diagonal lines through them representing structuralelements:

These buttons can be used to toggle off and on the relevant structural elements in the view.

Log structural elementsThe Outline view displays the following structural elements in the log:

• An individual log entry, and the parent node for errors and warnings.

• Error

• Warning

Listing and HTML Structural ElementsViewing the results of program execution (refer to Viewing the listing output and Viewing the HTMLoutput) causes the Outline view to display the following structural elements:

• Results parent node

• HTML tabular output

• Listing tabular output

Output ExplorerThe 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, use the Results Explorer.

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


50

Alternatively you can restart the server (as described in Restarting the server).

To display this viewTo add this view to the current perspective, select Window ➤ Show View ➤ Output Explorer.

OutputOutput items are associated with, and listed below, the server on which they were generated.

The following output items are shown under a server if that server has executed programs that havegenerated output of one or more of the following types:

• Listing output

• HTML output

• PDF output

Note: Log output is always shown under each server, regardless of whether any programs have been

executed.

Once you execute a program that generates output of one of the above types, you will see the relatedoutput nodes appear below the WPS server by which they were generated. There is only ever one nodeshown for each type of output under each registered WPS server.

Double-clicking on one of the output nodes opens the associated output in the editor associated withthat ouput type (or in Adobe Acrobat for PDF output). If the output type is anything other than logoutput, then, at the same time as the output is opened in the editor, the individual result elements arelisted in the Results Explorer.

For further information on the types of ouput, refer to Working with program output.

Results ExplorerThis view contains hierarchical links to all the results from every program that has been executed,grouped by server, since the last time that the particular server was started or restarted

Note:To view all output, including the log, use the Output Explorer.

To display this viewTo add this view to the current perspective, select Window ➤ Show View ➤ Results Explorer.


51

OutputOnce a program has been executed, an entry appears under the relevant server for every PROCthat produced output. For example PROC PRINT will produce an entry named The PRINT Procedure.Expand this link to find links to each type of output that has been generated.

For further information on the types of output, and the defaults, refer to Managing ODS output.

ProgressWhen you are running programs, their execution is confirmed in the Progress view. In addition,operations performed in the File Explorer are also visible here (both operations that are in progress, andthose that are complete).

Note:While a program is being executed, and during File Explorer and WPS Server Explorer operations,there is also a progress indicator displayed in the lower right hand corner of the Workbench. Thisindicator is displayed regardless of whether or not you have the Progress view open. If a program issubmitted to run while another one is still executing, it is listed as waiting to execute.

If you wish to halt the execution of a program, click in the Progress view (refer to Stopping anexecution).

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

File Explorer operationsA File Explorer operation remains in the Progress view until another operation is performed. Thisallows you to see the results of the operation, if desired, by clicking on the associated link. The resultantinformation box displays:

• Status: Success or Error• Operation: Copy, Rename, Delete, and so on.• Source: Original location of the file or folder• Destination : The target folder or root.• Exception: Any errors that occurred when the operation was performed.

Note:When part of an operation fails, the Workbench still attempts to complete any other parts of theoperation. For example, if you attempt to delete 5 files, and the first one fails, it will still attempt to deletethe remaining 4 files.


52

Console (for remote server standardoutput)The Console view is not used if you are only running programs on a local server. It can, however,be extremely useful if you are running your programs on a remote WPS server. In this scenario, allstandard output and standard error output produced by the server are echoed on the Console view.An example of its use could be to run an X statement in your program on the remote server which mightbe requesting a listing of the contents of a particular directory. In this case, the output from running theX statement is displayed.

It is also extremely valuable when a remote server fails to start, or terminates abnormally. In thissituation, error text is also displayed in the Console view.

Note:If you are using WPS Link, then, as explained in the Link Explorer, program output from a remoteserver can be viewed and manipulated from inside WPS Workbench, just as if the work had beenexecuted locally.

To display this wiewTo add this view to the current perspective, select Window ➤ Show View ➤ Other… ➤ General ➤ Console.

SearchThis view displays the results of searches that are carried out using the Search dialog. When you clickon an item in the results, the file opens automatically in the Editor at the exact place in the file wherethe item appears.

Proceed as follows:

1. To open the Search dialog and add the Search view to the current perspective, do one of thefollowing:

• Select Search ➤ Search.

• Select Window ➤ Show View ➤ Other… ➤ General ➤ Search and launch the Searchdialog....

2. Search using the following fields:


53

• Containing text: You can use any of the wild cards that are listed in the dialog.• File name patterns (separated by commas): After entering any of the listed wild card prefixes, you

can click Choose... to select the prefixes of file types to be searched for.• Scope: You can, for example, select Workspace to conduct a search of all open projects in the

Workbench, or Selected resources to conduct a search of only the active file.

Tip:You can also click Replace... to specify a string that is to replace the one in the Containing text field.


54

Working with viewsThis section describes how to manipulate the Workbench views both individually and as part of overallview stacks.

View stacksA view stack is a window formed by a collection of views that are all allocated the same area in aperspective. For example, the view stack below contains 2 views:

An individual view is opened in the view stack of which it was last a member. For example, if theProgress view was previously a member of our example view stack, then re-opening it restores it to thestack:


55

View stacks are an important concept to understand when it comes to moving, minimizing, maximisingand restoring views.

Opening a viewTo open a view in the Workbench:

1. Select Window ➤ Show View.

2. If the required view is not immediately listed, then select Other... from the drop-down menu to see acomplete list of views.

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

3. Highlight the view that you wish to open.4. Click OK to complete the task.

The view you select will open (if it was not already open) and will automatically become active. Itsopening position will be in the view stack of which it was last a member.

Closing a viewTo close a view that is open in the Workbench:

1. Ensure that the view is active by clicking on its tab.2. Click on the close icon in the tab of that view.

If you close all the views in one of the View stacks, then the adjacent view stack will expand to take upthe available space.

Note:An exception to the above is the Editor view, which always remains open, even after you close all theprograms that are open within it.

Moving a viewTo move a view to a new window in the Workbench:

1. Click on the view tab or title bar and, while you keep pressing on the left mouse button, drag theview over the Workbench window where you want your view to appear.


56

2. Without dropping the view, move it around from side to side and up and down. You will see the newwindow start to divide, according to the dimensions of the view. Vertical and horizontal lines indicatewhere the view will appear if you drop it in its current location..

3. Drop the view where you would like it to appear.4. The view appears in its new view stack. If you dropped it onto an existing view stack, then the views

in the original stack reduce in size to accommodate the new view.

Note:You can also move a view to a window outside Workbench, so that it is detached. Refer to Detachingand re-attaching a view.

Detaching and re-attaching a viewYou can detach any individual view from the Workbench to create a new, detached window.

To detach a view:

Click on the view tab or title bar and, while you keep pressing on the left hand mouse button, drag theview off the main user interface. When you drop the view, a new window is created on your desktopaway from the Workbench.

To re-attach the view:

1. Drag the tab of the detached window (not its title bar) over the main Workbench window. Rectangleswill appear to incidate where the view can be dropped.

2. Drop the view in the desired position. The detached view should now revert to being docked in theWorkbench.

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

Resizing a viewIn order to resize a view, you have to resize its associated view stack, which will then resize all theviews within it.

1. Move your mouse over the border between the particular view stack or window, and its adjacentview stack or window (whether this is to the side, above or below), until the cursor changes to the or resize icon.

2. Press your left mouse button and keep it pressed while you drag the border side to side, or up anddown.

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


57

Minimising a viewIn order to minimise a view, you have to minimise its associated view stack, which will then minimise allthe views within it. The minimised views will then be represented by icons on either the left or right ofthe Workbench, so that you can restore them, for example:

To minimise a view stack or window, click Minimise button on the view stack or window.

Maximising a viewIn order to maximise a view, you have to maximise its associated view stack, which then fills the entireWorkbench interface.

To maximise a view stack or window, do either of the following:

• Click Maximise on the view stack or window.

• Double-click on either the view stack's toolbar or the tab of one of the views within the stack.

Maximising a view causes it to occupy as much space as it possibly can. When this happens, otherviews that occupy the same view stack are also maximised, but the original view remains on top, and isstill active. All other view stacks are minimised to the edges of the Workbench window, where they arerepresented as icons.

Restoring a viewIn order to restore a view to its 'normal' state after it has been minimised or maximised, you have torestore its associated view stack.

To restore a view stack or window that has been maximised, do either of the following:


58

• Click on the Restore button of the view stack or window.

• Double-click on either the view stack's toolbar or on the tab of one of the views within the stack.

To restore a view stack or window that has been minimised, do either of the following:

• Click the Restore icon above the minimised view stack to restore all the views in that stack.

• Right-click on the relevant icon on either the left or right of the Workbench to display the contextmenu, and then select Restore:

PerspectivesThe positions of available views, windows, view stacks, menu items, and toolbar buttons, togetherwith any other items that make up the general layout of WPS Workbench, together constitute a perspective.

We have already covered the default WPS perspective. However, this can be customised to look theway you want by moving, resizing, adding or removing different views (refer to Working with views). TheWorkbench allows you to save customised perspectives and to switch between different perspectives.

WPS remembers when you next open the Workbench, exactly how the windows and views, and so on,were arranged, when you last closed it. You do not even have to save a perspective to ensure that thishappens. This ensures that your favourite perspective is immediately visible as soon as you openthe Workbench.

Opening a perspectiveTo open a different perspective:

1. To see a list of all the available perspectives in the Open Perspective dialog, either selectWindow ➤ Open Perspective ➤ Other or click the Open Perspective icon in the top right of thescreen:


59

2. Highlight the perspective that you wish to open.3. Click OK to complete the task.

When you open a perspective, its name is highlighted by default in the top right of the Workbench.If you have other perspectives available, they are also listed in this area, to the right of the OpenPerspective icon, so that you can click on them to switch between them quickly.

Closing a perspectiveThe quickest way to close a perspective is to go to the area to the right of the Open Perspective icon, right-click on the perspective required, and then select Close. Alternatively:

1. If you have more than one perspective open, ensure that the Workbench is displaying the one thatyou wish to close.

Note:To switch perspective, look in the area to the right of the Open Perspective icon, and then clickon the perspective required.

2. Select Window ➤ Close Perspective.

Note:If you wish to close all the perspectives, so that only the Default WPS perspective remains availablefor selection, select Window ➤ Close All Perspectives. Your interface will go blank. To restore thedefault perspective, select Window ➤ Open Perspective ➤ Other ➤ ➤ WPS (default).

Resetting a perspectiveYou can reset the current perspective back to its default layout at any time, by proceeding as follows:

1. Select Window ➤ Reset Perspective.

2. You are prompted for confirmation that you wish to reset the perspective. Click Yes to confirm thatyou wish to do so.


60

Saving a perspectiveIf you have changed the layout of a perspective, you can save it under a user defined name for futureuse, as follows:

1. Select Window ➤ Save Perspective As….

2. Enter a name for the perspective at the top of the Save Perspective As... dialog.3. Click OK to continue.

If a perspective is already saved with the name you have just entered, you will be asked if you wishto overwrite it with the new perspective layout.

The new perspective appears in the top right of the Workbench, to the right of the Open Perspective icon.

Note:A perspective derives its icon from the one that you had open when you saved it.

Deleting a perspectiveTo delete a perspective:

1. Select Window ➤ Preferences.

2. From the left hand tree view of the Preferences window, select General ➤ Perspectives.

3. From the list of Available perspectives, click on the perspective that you wish to delete.4. Click Delete to remove the perspective permanently. There is no confirmation prompt.

Note:You can only delete user-defined perspectives. In other words, you cannot delete a perspective thatwas supplied with WPS, including the default WPS perspective.

5. Click OK to close the Preferences window.


61

ProjectsA project is a Workbench representation of a parent folder containing objects such as programs,files and folders. This parent or project folder is defined by a Project Definition File.

WPS uses a project to hold the files and folders that relate to each other. For example, you might haveone project containing programs that are still under development, another project for monthly reportingapplications, and so on.

Each project is in turn held in its own parent folder referred to as a workspace. You can only work withone workspace at a time within the Workbench, but you can switch between different ones as required(refer to Switching to a different workspace). The Project Explorer is used to display and manage thecurrent workspace and the projects it contains.

There is no limit to the number of projects you can have open within WPS Workbench, or to thenumber of folders and files that a project may contain. Files may also be of any type, and all the typicaloperations that you would expect to be able to perform on files are available, including the ability toexecute files identified as SAS programs (that is to say, any files with the extension .sas or .wps).

Workspace objects can be managed using Local history, and they can also be exported to archivesor to other folders in a file system on a local or remote host, and such archives may also be imported inthis view.

Note:If you would prefer to access a file system directly in order to manage programs (rather than useprojects), then this is possible via the File Explorer (although using this will not give you access to Local history).

Project Definition FileThere is a project definition file called .project in the root directory of a project. This file containsinformation about the project that is used internally by the Workbench. This file is not normally displayedby the Project Explorer. However, if you look at the project folder outside of WPS Workbench, you cansee it.

Caution:

• Do not delete or edit this file.• Do not move this file from the root directory of the project folder, even into another project folder.• Do not copy or import this file into another project folder.


62

Managing projectsThis section of the guide covers the creation and manipulation of projects, and the files within them.

Creating a new projectTo create a new project:

1. Launch the New Project wizard by either clicking the drop-down next to the New icon inthe top left hand corner of the window and selecting Project, or by selecting File ➤ New ➤ Project.

You will see the first page of the New Project wizard.2. Expand the General folder and highlight the Project node.

3. Click Next.4. Enter the new Project name.

Provided that the name of the new project is not the same as that of an existing folder, a new folderwill be created.

5. (Optional) If you wish to change the default location of the new project, deselect Use defaultlocation and specify the new Directory, using Browse where required.

Caution:If you choose a directory outside of the active workspace, then you need to be aware that, by addingit to the project, you are not moving the folder. It is merely referred to by the project.

6. You need not concern yourself with the Project References page of the New Project wizard as thisis mainly for Eclipse use. Therefore, click Finish to create the new project.

Creating a new folder in a projectYou can have any number of folders and sub-folders in a project. To create a new one:

1. Launch the New Folder wizard by frst ensuring that the parent item is open, and then doing one ofthe following:

• Right-click on the Project or Folder within which you wish to create the new folder, andselect New ➤ Folder.

• Select File ➤ New ➤ Folder.

• Click the drop-down next to the New icon in the top left hand corner of the window andselect Folder.


63

You will see the first page of the New Folder wizard.2. The parent defaults to the current project or folder.

3. Near the bottom of the window, type in the new Folder name.4. (Optional) Clicking Advanced allows access to folder configuration options.

• Use default location. This is the default option. The folder will be created as a file system folder,in the original location.

• Folder is not located in the file system (Virtual Folder). The folder will only exist in theworkspace and no folder will be created in the associated file system. You can create links toother files and folders within this new folder, and also add other virtual folders. To do this, simplydrag and drop your other project resources into the virtual folder. It is not possible to createphysical files and folders within virtual folders. You can use this option to organise an alternativeview of files and folders independent 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 thatyou make to the contents will also affect the folder in the associated file system. The Workbenchwill record any changes to files that you make with the Workbench, allowing the use of Localhistory with these files. Use Browse... in order to select the folder in your file system to which tolink.

5. Click Finish to complete the task.

Creating a new file in a projectTo create a new file under an existing Project, or under an existing Folder in a project, proceedas follows:

1. Launch the New File wizard by doing one of the following:

• Ensure that you have the Project Explorer open (Window ➤ Show View ➤ ProjectExplorer), right-click on the object under which you wish to create the new file, and then selectNew ➤ File.

• Select File ➤ New ➤ File.

• Click the drop-down next to the New icon in the top left hand corner of the Workbenchwindow and select File.

You will see the File dialog.2. Ensure that the required parent folder is selected at the top of the dialog.3. Near the bottom of the dialog, type in the new file name.

If you specify a file extension that the system recognises (for example, .sas or .wps or for a program,or .doc for a Microsoft Word document) then the new file will be associated with the appropriateeditor. If no file extension is specified, or if the extension is not one that the system recognises, thenthe default action is to associate the new object with WPS Workbench Text Editor.


64

4. (Optional) Select Advanced and, if required, Link to file in the file system. Then use Browse… toselect an existing file, from any project, to which to link the new file.

Note:This step creates a shortcut to the existing file, and the contents of the latter will immediately bewritten to the new file. Any changes that you make to these contents will now also affect the file inthe file system. The new file has a small arrow in the right hand corner of its associated icon, forexample , to indicate that it is linked. To examine the nature of the link at any time, and change itif needed, right-click on the project file with the icon, and select Properties followed by Resource.


The new file appears in the Project Explorer, under the selected Project or Folder.

Note:To create a new program file specifically, within which you can create a new Program for executionin WPS, refer to Creating a new program file in a project.

Creating a new program file in a project

To create a new program file below an existing Project, or below an existing Folder in a project,proceed as follows:


2. Launch the New Program wizard by doing one of the following:

• Right-click on the object below which you wish to create the new progam, and then selectNew ➤ Program.

• Select File ➤ New ➤ Program, or File ➤ New ➤ Untitled Program.

• Click the drop-down next to the New icon in the top left hand corner of the Workbenchwindow and select Program or Untitled Program from there.

You will see the WPS Program dialog.

Note:If you selected Untitled Program, then the new program automatically opens in the SASEditor ready for you to start typing in code, and it has a default name of Untitled n.sas, where nis the next number in the sequence. You can now start typing in code in accordance with Creating anew program, and save the file to the required location.

3. Ensure that the required parent folder is selected at the top of the dialog.4. Near the bottom of the dialog, type in the new file name.


65

Note:The Workbench may suggest a default name such as Program1.sas, or, if there is already aprogram using this name, Program2.sas, and so on. However, you can change the extension to.wps if you prefer, as files with both suffixes are handled as SAS programs by WPS.

5. (Optional) Select Advanced and, if required, Link to file in the file system. Then use Browse… toselect an existing file, from any project, to which to link the new file.

Note:This step creates a shortcut to the existing file, and the contents of the latter will immediately bewritten to the new file. Any changes that you make to these contents will now also affect the file inthe file system. The new file has a small arrow in the right hand corner of its associated icon, forexample , to indicate that it is linked. To examine the nature of the link at any time, and change itif needed, right-click on the project file with the icon, and select Properties followed by Resource.


The new program appears in the Project Explorer, under the selected Project or Folder, and automatically opens in the SAS Editor ready for you to start typing in code, in accordancewith Creating a new program.

Opening a project fileWhen using the Project Explorer, you have control over exactly how the Workbench should open yourfiles, by selecting specific editors. Refer to Working with editors.

Moving a project fileTo move any folder, file, program, or any other object, between projects, or between folders within thesame project, proceed as follows:


2. Highlight the object that you wish to move.3. Move it by doing one of the following:

• Drag it to the required project or folder, making sure to keep the left mouse buttondepressed until the system indicates that you can drop it.

• Select the option File ➤ Move..., to display the Move Resources dialog. You can then select thenew destination project or folder within the dialog, Preview the move as required, and then clickOK to complete the move.


66

Note:If you are not happy with the completed move, you can revert it by selecting Edit ➤ Undo MoveResources.

Tip:You can also drag and drop objects between Microsoft Windows Explorer and the Workbench Project Explorer.

Copying a project fileTo copy any folder, file, program, or any other object, between projects, or between folders within thesame project, proceed as follows:


2. Highlight the object that you wish to copy.3. Do one of the following:

• Hold down the the Ctrl key, and drag it to the required project or folder while keeping theCtrl key depressed. A dialog will be displayed asking whether you want to copy the object or linkit to another location.

• Copy (by either right-clicking on the object and selecting Copy, or selecting Edit ➤ Copyfrom the menu), and then paste (by either right-clicking on the destination project or folder andselecting Paste, or selecting Edit ➤ Paste from the menu).

Note:If you are not happy with the completed copy, you can revert it by selecting Edit ➤ Undo CopyResources.

If you try to paste the object into the same location from which you are copying, you will be promptedto enter a new name for the copy (the default name is Copy of <object name>).

Tip:You can also copy objects between Microsoft Windows Explorer and the Workbench ProjectExplorer, by copying and pasting or dragging and dropping. In addition, you can copy and pastefiles between the Project Explorer and File Explorer, and vice-versa.

Renaming a project or project fileTo rename an object, or even the project itself:


67


2. Highlight the object or project that you wish to rename.3. Display the Rename Resource dialog by either right-clicking on the object and selecting Rename...

from the context menu, or selecting File ➤ Rename… from the main menu.

4. Enter the New name in the Rename Resource dialog.5. Either press Enter on your keyboard, or click OK, to complete the operation and close the dialog.

Linking the active file to the Project ExplorerIf you have several files from different projects open in the Editor, you can configure the ProjectExplorer to expand a project's contents automatically so that each open file is linked to the ProjectExplorer. This means, for example, that the name of a program is displayed and highlighted within itsfolder each time that you switch the focus to that program in the Editor.

Restriction:This linking feature does not work for programs opened with the File Explorer.

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

2. On the view's toolbar, click the Link with Editor button.

This toggles the linking feature on or off.

Deleting a file from a projectThe removal of an entire project is covered in Deleting a project.

To delete an individual object from a project, proceed as follows:

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

2. Highlight the object that you wish to delete.3. Display the Delete Resources dialog by either right-clicking on the object and selecting Delete

from the context menu, or selecting Edit ➤ Delete from the main menu.

4. Press OK to confirm you wish to proceed with the deletion.5. The dialog is closed and the object is removed from its parent project.

Note:If you have multiple copies of the same object within various folders and projects, only the actualcopy that is highlighted is removed.


68

If you delete objects as above, from within the Project Explorer, rather than using the operatingsystem's deletion tools, you can use the Workbench's Restoring from local history feature.

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, refer to the Copying a project file section in this guide.

Deleting a projectTo delete a project:


2. Right-click on the project and, from the context menu, select Delete.

3. A message is displayed allowing you to confirm or cancel the deletion.

Warning:You will also see a check box option Delete project contents on disk (cannot be undone).Selecting this option will permanently remove the project folder and all its contents from the filesystem.

You also have the option of being able to Preview the information associated with the resource thatyou are about to delete. This will highlight any potential problems.

If you opt not to remove the contents from the file system, you can subsequently select File ➤ Import ➤ General ➤ Existing Project into Workspace, to redisplay the project in theWorkbench.

4. Click OK to proceed with the deletion.

Closing and re-opening a projectWhen you have multiple open projects in the Workbench, you might like to close some projectsto ensure that you do not accidentally manipulate the wrong programs:


2. Highlight the project that you wish to close.


69

3. Either right-click on the project and select Close Project, or select Project ➤ Close Project from themenu.

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.

Note:When you need to re-open the project:

1. Open the Project Explorer ( Window ➤ Show View ➤ Project Explorer).

2. Highlight the closed project.

3. Either right-click on the project and select Open Project, or select Project ➤ Open Project.

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

1. You need to import files into an existing project. If you do not have an existing project, refer toCreating a new project.

2. Launch the Import wizard by either right-clicking on the project and selecting Import..., or selectingFile ➤ Import… from the main menu.

You will see the first page of the Import wizard.3. Expand the tree under the General node.

4. Select one of the following options:

• File System - Use this if the files and folders to import are not archived in a single file.• Archive File - Use this if the files and folders to import are archived in one file (as a zip, tar or

tar.gz, for example).5. Click Next >.6. In the blank From field at the top of the screen, you need to specify the location of the file(s) to

import, using Browse… as required.7. You will see a list of the files and folders that are available to import. Ensure that all the objects that

you wish to import are selcted.

Tip:You are advised not to select the parent folder of the files to import - otherwise, in your new project,you will end up with your imported files inside a sub-folder that relates to this parent folder.

Restriction:Do not import a Project Definition File ( .project ). Otherwise, it will overwrite the one in theproject that you are about to select in the next step as the Into Folder'.


70

8. Use Browse… to specify the Into folder (that is to say, the folder into which the file(s) selected inthe From field will be imported).

9. Click Finish.

The files have been imported into the selected project.

Exporting a projectTo make a copy or backup of a project and all the files and folders contained within it:


2. Highlight the project that you wish to export.

3. Launch the Export wizard by either right-clicking on the project and selecting Export..., or selectingFile ➤ Export… from the main menu.

You will see the first page of the Export wizard.4. Expand the tree under the General node.

5. Select one of the following Export Destination types:

• File System - Makes a copy of your project folder and the files and sub- folders it contains.

• Archive File - Creates a single compressed zip file in the export location.

Note:The Workbench can read and write zip files without the need for any additional proprietarysoftware.

6. Click Next.7. (Optional) You can now select or de-select any files and folders from the default list to be exported.

Because you highlighted a project before you began the export process, the default list is madeup from this project. If you want to change your selection, you could click Deselect All to ensurethat nothing is selected, and then, in the left hand window, select the project that you want toexport instead (this will ensure that all the objects it contains are selected). Experiment with theother options to select specific files and folders.

8. In the blank To field in the middle of the Export screen, you need to specify the target location. Youcan use Browse… as required.

9. Click Finish to start the export process.

You now have a backup of the project. Depending on which Export Destination you selected, if youlook at the target location you selected, you will see either a zip file, or all the copied files and folders.


71

Working with multiple projectsMore than one project can be open at any one time in the Workbench. There are several ways toend up with multiple projects in the Workbench:

• Creating a new project

• Importing the sample and other projects

• Copying a project

Note:You can move, copy/cut and paste, items between projects.

Switching to a different workspaceTo switch to a different workspace, so that you can display or create a different group of projects:

1. In order that you can see the outcome of switching workspaces, first ensure that you have theProject Explorer open ( Window ➤ Show View ➤ Project Explorer).

2. Select File ➤ Switch Workspace. If the workspace to which you wish to switch is not immediatelydisplayed, select Other… to display the Workspace Launcher (refer to the instructions there toselect a different workspace).

3. If you selected an alternative workspace without displaying the Workspace Launcher, then theWorkbench is automatically restarted to display the new workspace. Otherwise, launch the restart byclicking OK on the Workspace Launcher.

Local historyThe Workbench maintains a local history of modifications to programs or other project files changedin the Workbench via the Project Explorer.

Note: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 Project Explorer (refer toCopying a project file).

Caution:Local history is not available when managing files through the File Explorer.


72

History of EditsEach time you save a project file in the Workbench, a snapshot of the current contents of the file isadded to the Workbench's local history. This history provides the ability to take any of your currentprograms and compare or replace them with local history (refer to Comparing with local history andReplacing with local history, respectively). Each modification in the local history is uniquely representedby the timestamp for each occasion the file is saved.

Note:If you modify a file outside of the Workbench, or modify a file opened with the File Explorer, norecord will be added to the history.

History of DeletionsEach time you delete a program or file via the Project Explorer (refer to Deleting a file from aproject) , the edit history of the item being deleted is 'transferred' to the local history of the containingproject or folder. This not only allows you to restore it from local history, but also to select whichparticular state from the item's history to restore.

Local History PreferencesLocal history preferences allow you to control how long to keep the local history, how many entries tokeep in the history, and the maximum file size that can be recorded.

Comparing with local historyTo compare a current saved project file with a previous version:

1. Select the file for which you wish to compare versions in either of the following ways:

• Ensure that you have the Project Explorer open (Window ➤ Show View ➤ ProjectExplorer) and highlight the file.

• Open the file in the Editor and ensure that it is the active file.2. Right-click and, from the context menu, select Compare With ➤ Local History….

A History window opens showing the list of program revisions with revision times.3. From the list of revisions, double-click a particular revision with which you wish to compare the

current version of the file.

The Text Compare window immediately opens showing the differences (marked in grey) betweenthe two versions. The current version is shown on the left, with the revised version on the right.

4. The following toolbar buttons in the Text Compare window provide shortcuts to options that allowyou to navigate through the files:

• Select Next Difference - when available, this option highlights the next difference.


73

• Select Previous Difference - when available, this option highlights the previous difference.

• Select Next Change - when available, this option highlights the next modification.

• Select Previous Change - when available, this option highlights the previous modification.

5. If you wish to replace the entire current version with a previous version, then proceed as inReplacing with local history. If you simply wish to make more selective changes in the left handwindow, based on what you see in the Text Compare window, the following toolbar buttons in theText Compare window provide shortcuts to options that allow you to merge changes from one file tothe other:

• Copy Current Change from Right to Left - this option copies the change/difference that iscurrently highlighted, from the right pane to the left pane.

• Copy All from Right to Left - this option copies the entire contents of the right pane to theleft pane.

6. Once you have made your changes, select File ➤ Save.

7. Close the Text Compare window by doing one of the following:

• Move the mouse over the tab and then select Close (this appears to the right of the name).

• Right-click on the tab and select the Close option.• Select File ➤ Close.

Note:If you try and close a window when there are unsaved changes, you will be asked whether or notyou wish to save them.

Replacing with local historyTo revert a program in a project back to a previous saved version:

1. Do one of the following:

• Ensure that you have the Project Explorer open (Window ➤ Show View ➤ ProjectExplorer) and highlight the file that you wish to replace with a previous version.

• Open the file in the Editor and ensure that it is the active file.2. If you simply wish to replace the current version with the previous version, right-click, and, from

the context menu, select Replace With ➤ Previous from Local History. However, if you wish toexplore the previous versions before making a choice, proceed from the next step.

3. Right-click, and, from the context menu, select Replace With ➤ Local History….

A Compare dialog opens showing the list of program revisions.4. Double-click on a particular revision that you wish to compare against the current version.


74

The current version and selected previous version are displayed with the differences highlighted.The current version is entitled Workspace File, and the revision you selected is entitled LocalHistory.

Tip:You can highlight and copy a portion of text from a previous version that you wish to use elsewhere.Then, after clicking Close in the upper right hand corner of the dialog, or Cancel in the bottomright hand corner, you can paste your piece of text into a different program or file.

5. Once you are sure that the Local History version displayed is the one that you wish to use insteadof the current version, click Replace to supersede the Workspace File with the Local History andclose the Compare dialog.

Restoring from local historyA program or any other project file that has been deleted via the Project Explorer, can berestored as follows:

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

2. To see all the files that have been removed from a project, right-click on the project. To seejust the files that have been removed from a folder, right-click on the folder. Then, from theparticular context menu, select Restore from Local History... .

The Restore from Local History dialog opens showing the files that are available to be restored.3. Select the check box next to each file to be restored.

Note:If a selected file has a local history, then the previous revisions of the file are displayed on theright hand side of the dialog, grouped by date. Once you highlight a revision, its details are displayedin the bottom pane of the dialog. Ensure that you highlight the revision that is to be restored, beforecontinuing.

4. Click Restore to put the selected file(s)/file revision(s) back into the original project/folder and closethe Restore from Local History dialog.

Local history preferencesBy default, the Workbench keeps seven days of local history for each individual project file, with amaximum of fifty versions for each file. There is also a default of 1 MB of storage allocated for eachprogram's local history.

The above settings can be changed as follows:


75

1. Select Window ➤ Preferences… ➤ General ➤ Workspace ➤ Local History.

The Local History dialog is displayed.2. Set any of the following as required:

• Days to Keep Files - The number of days that you want to keep records for any one project file.For example, if you type 20, then a history of saved versions from the last twenty days will bekept. The default value is 7 days.

• Maximum Entries per File - The number of versions to keep for any one project file. If thisnumber is exceeded, the oldest changes are discarded to make room for the new changes. Thedefault is 50 versions per file.

• Maximum File Size (MB) - The maximum file size (in MB) for a project file's local history. If thissize if exceeded, then no more local history is kept for the file. The default size is 1MB.

Note:The Days to Keep Files and Maximum Entries per File are only applied when the local history iscompacted on server shutdown.

Comparing and merging multiple filesYou can carry out either two- or three-way comparisons.

Note:Three-way comparisons show the differences between three different versions of a file, for examplethe differences between the resource in the Workbench, the version of the resource that is committedin a branch, and the common ancestor on which the two conflicting versions are based. This feature ismost useful when merging resources and there has been a conflict during synchronization. Conflictsare shown in red, incoming changes in blue, and outgoing changes in grey. If a common ancestorcannot be determined, for example because a resource with the same name and path was created andcommitted by two different developers, the comparison becomes a two-way comparison.

To do this:

1. Ensure that you have the Project Explorer open (Window ➤ Show View ➤ ProjectExplorer) and highlight the files that you wish to compare (up to three).

2. Right-click and, from the context menu, select Compare With ➤ Each Other.

If you are doing a two-way comparison, a Text Compare window immediately opens showing thedifferences (marked in grey) between the two versions. If you are doing a three-way comparison,you are first prompted to select the common ancestor - that is say, the file against whichcomparisons will be made. In the Text Compare window, the two versions other than the commonancestor are shown in adjacent panes, although you also have the option to show this latter pane aswell via the following option on the toolbar:


76

• Show Ancestor Pane - in a three-way comparison, this option shows the common ancestor.Click again to hide it.

Note:If you wish to switch between comparisons, you can use the following option: Togglebetween Two-Way and Three-Way Comparison - this switches between the two-waycomparison (ignoring the common ancestor) and three-way comparison.

3. The following toolbar buttons in the Text Compare window provide shortcuts to options that allowyou to navigate through the files:

• Select Next Difference - when available, this option highlights the next difference.

• Select Previous Difference - when available, this option highlights the previous difference.

• Select Next Change - when available, this option highlights the next modification.

• Select Previous Change - when available, this option highlights the previous modification.

4. The following toolbar buttons in the Text Compare window provide shortcuts to options that allowyou to merge changes from one file to the other:

• Copy Current Change from Right to Left - this option copies the change/difference that iscurrently highlighted, from the right pane to the left pane.

• Copy All from Right to Left - this option copies the entire contents of the right pane to theleft pane.

• Copy Current Change from Left to Right - this option copies the change/difference that iscurrently highlighted, from the left pane to the right pane.

• Copy All from Left to Right - this option copies the entire contents of the left pane to theright pane.

5. Once you have made your changes, select File ➤ Save.

6. Close the Text Compare window by doing one of the following:



Note:If you try and close a window when there are unsaved changes, you will be asked whether or notyou wish to save them.


77

Managing files within the FileExplorerIn this section of the guide we will look a little more closely at how you can manipulate the variousobjects in the available file systems using the File Explorer.

As previously explained in The Project and File Explorer views, the benefit of using the File Explorer isthat you can access files and folders on remote systems as well as local ones.

Creating a new folder in a file systemFolders can be created wherever you have appropriate operating system privileges for the particularlocal or remote host.

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

2. Launch the New Folder dialog by right-clicking on the Directory Shortcut or Folder belowwhich you wish to create the new folder, and selecting New ➤ Folder.

You will see the New Folder dialog.3. Ensure that the required parent Directory Shortcut or Folder is selected. You will see that

the container from where you opened the context menu is currently selected. However, you maychoose to create the folder on an entirely different host.

4. Near the bottom of the window, type in the new Folder name.5. Click Finish to complete the task.

Creating a new file in a file systemTo create a new file in an existing file system, proceed as follows:

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

2. Launch the New File dialog by right-clicking on the Directory Shortcut or Folder belowwhich you wish to create the new file, and then selecting New ➤ File.

The New File dialog is displayed.


78

3. Ensure that the required parent Directory Shortcut or Folder is selected.

4. Near the bottom of the dialog, type in the new file name.

If you specify a file extension that the system recognises (for example, .sas or .wps or for a program,or .doc for a Microsoft Word document) then the new file will be associated with the appropriateeditor.


The empty file is created in the specified location.

Note:To create a new program file specifically, within which you can create a new Program for executionin WPS, refer to the next section.

Creating a new program file in a file systemTo create a new program file under an existing file system Directory Shortcut or Folder,proceed as follows:

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

2. Launch the New Program wizard by doing one of the following:

• Right-click on the object below which you wish to create the new progam, and then selectNew ➤ Program.

• Select File ➤ New ➤ Program, or File ➤ New ➤ Untitled Program.

• Click the drop-down next to the New icon in the top left hand corner of the Workbenchwindow and select Program or Untitled Program from there.

You will see the WPS Program dialog.

Note:If you selected Untitled Program, then the new program automatically opens in the SASEditor ready for you to start typing in code, and it has a default name of Untitled n.sas, where nis the next number in the sequence. You can now start typing in code in accordance with Creating anew program, and save the file to the required location.

3. Ensure that the required parent Directory Shortcut or Folder is selected.

4. Near the bottom of the dialog, type in the new file name.

Note:The Workbench may suggest a default name such as Program1.sas, or, if there is already aprogram using this name, Program2.sas, and so on. However, you can change the extension to.wps if you prefer, as files with both suffixes are handled as SAS programs by WPS.


79


The new program appears in the File Explorer, under the selected Directory Shortcutor Folder, and it will automatically open in the SAS Editor ready for you to start typing in code, inaccordance with Creating a new program.

Opening a file in a file systemOpening files with the File Explorer allows the Workbench to decide which is the most appropriateeditor to open them with.

1. Ensure that you have the File Explorer open.

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

The file is opened according to the extension, for example:

• Program files (those with .wps and .sas file extensions) are opened in the SAS Editor.

• Text files (.txt) are opened in the Text Editor.• XML files (.xml) are opened in the Text Editor.• HTML files (.html) are opened inside the Workbench where possible (this is platform-dependent).

Other types of file can also be opened in the Workbench, but this depends on the operating system.

Note:On some operating systems, the Workbench will attempt to open the application associated with thefile, even if it cannot be opened inside the Workbench itself.

Moving a file within a file systemYou can move files to other folders in your local and remote connections, by for example:

• Moving files using Cut and Paste.• Moving files using Drag and Drop.

Moving files using Cut and PasteYou can move File Explorer objects by using the options on the Edit or right-click menu, or by usingthe keyboard shortcuts for your operating system.

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


80

2. Select the object that you want to move and select Cut, or else use the keyboard shortcut for Cut foryour operating system (for example CTRL + X).

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 (for exampleCTRL + V).

The progress of the operations can be viewed in the Progress view.

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

Moving files using Drag and DropYou can drag and drop files and folders to move them:

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

2. Click on the object that you wish to move.3. Press your left mouse button, and drag it to the required Shortcut Directory or Folder while

keeping the mouse button depressed.4. Release the mouse button to drop the object onto the selected location.

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

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

Copying a file within a file systemYou can copy files to other folders in your local and remote connections, by for example:

• Copying files using Copy and Paste.• Copying files using Drag and Drop.

Copying files using Copy and PasteYou can copy File Explorer objects by using the options on the Edit or right-click menu, or by using thekeyboard shortcuts for your operating system.


81

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

2. Select the object that you want to copy and select Copy, or else use the keyboard shortcut for Copyfor your operating system (for example CTRL + C).

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 (for exampleCTRL + V).

The progress of the operations can be viewed in the Progress view.

Tip:You can also select multiple objects if you wish to copy more than one object at once. In addition, youcan copy and paste files between the Project Explorer and File Explorer, and vice-versa.

Copying files using Drag and DropYou can drag and drop files and folders to copy them:


2. Click on the object that you wish to copy.3. Press the left mouse button and Control key, and keep them pressed as you drag the object to the

required Shortcut Directory or Folder (depression of the Control key causes a plus symbol(+) to appear next to the mouse pointer).

4. Release the mouse button and Control key to drop a copy of the object onto the selected location.

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

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

Renaming an object within a file systemTo rename a file system object:


2. Right-click on the required object and select Rename from the context menu.3. The Rename File dialog is displayed, allowing you to overwrite the existing object name with a new

name.4. Press Enter or clicking OK will complete the operation and close the dialog.


82

Note:You may need to refresh the connection in the Link Explorer view to see the change. (To do this, selectthe connection, and then either right-click on it and select Refresh from the context menu, or press theF5 key.)

Deleting an object from a file systemTo delete an object from a file system, proceed as follows:

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

2. Right-click on the required object and select Delete from the context menu.

3. From the menu select the option Delete.

4. Click OK to confirm that you wish to proceed with the deletion.

Warning:Once you confirm the deletion of the object from the file system using the File Explorer, the operationcannot be undone.

Note:If you are deleting a file using the Project Explorer (refer to Deleting a file from a project), ratherthan using the File Explorer, you will be able to restore the files if required (refer to Restoring fromlocal history).

WPS File Explorer Preferences (HiddenFiles)Under Window ➤ Preferences… ➤ WPS ➤ File Explorer you can select Show hidden files andfolders to allow hidden files and folders to be displayed on a Windows platform, or else the files andfolders that start with a '.' character on UNIX-based systems.


83

PreferencesThere are many user settings, controls and defaults that you can control via theWindow ➤ Preferences… panel.

Most of the relevant Preferences are incorporated into the sections of this guide to which they directlyrelate. This particular section covers just the following general options:

• Preferences filter• General Preferences• Shortcut Key Preferences• Backing up your Preferences

Any preferences that are not described in this guide can be looked up in the Eclipse-specificWorkbench User Guide.

Preferences filterThe Preferences window has a filter function which can help you find preference pages quickly.

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


84

By way of an example, type the word log into this box one letter at a time and see how the window isfiltered to display only those pages whose titles or sub-titles contain the text that has been entered as afilter.

To stop filtering, click on the Clear button that has now appeared on the right of the text box, and allavailable Preferencespages will then be redisplayed in the tree view.

General PreferencesUnder Window ➤ Preferences ➤ General are controls that not only affect programs, but also othertypes of files and other general aspects of WPS Workbench. Here are some of the salient top-levelitems that you may wish to consider:


85

Always Run in BackgroundSome operations such as running programs, or refreshing a project containing many files, cantake a long time to be executed. When the Always Run in Background option is enabled, itallows such tasks to run without displaying the Executing window.If this option is left in its default unchecked state, then the Executing window has a Run inBackground button that will have the same effect when selected.

Show Heap StatusWhen this option is selected, then an indicator is displayed showing information about usageof the current Java heap, which is the segment of operating system memory used by theWorkbench to manage its GUI. This indicator appears in the bottom of the window to the left ofthe server status, for example:

To increase your Java heap storage, update the last two lines of the file<wps_install_root>\eclipse\workbench.ini to something like -vmargs -Xmx1024mand then restart the Workbench. The -Xmx argument is the one that decides the Java heapstorage limit, and in this case 1024 megabytes is the value.

Workbench save interval (in minutes)

The field indicates how often the state of the Workbench, including perspective layouts, isautomatically saved to disk (the default is 5 minutes). Set to 0 if you want to disable this auto-saving.

Open ModeThis preference controls the way you open objects in the Workbench. Select from the following:

• Double click - Single-clicking on a resource will highlight it and double-clicking on it will openit in an editor. This is the default action.

• Single click (Select on hover) - Hovering the mouse cursor over the resource will highlight itand clicking on it once will open it in an editor.

• Single click (Open when using arrow keys) - Selecting a resource with the arrow keys willautomatically open it in an editor.

Depending on which view has focus, selecting and opening a resource may result in behaviourdifferent from that outlined above.

Change FontSelect Window ➤ Preferences ➤ General ➤ Appearance ➤ Colors and Fonts ➤ scroll down theBasic entries until you find Aa Text Font. Highlight this and then click Edit to apply a differentfont.


86

Shortcut Key PreferencesIf you wish to change any key bindings, select Window ➤ Preferences ➤ General ➤ Keys, and, underthe Default scheme, search for the WPS category. Then filter the Category and Binding to display thefollowing screen:

If you wish to change any of the bindings, proceed as in the following example, where we want to bindCtrl + 5 to the Cancel Edits command:

1. Ensure that the Cancel Edits command is selected.2. In the Binding text box, press Ctrl + 5.


87

3. The right-most column (User) indicates that this is a user binding by displaying a U. If there wasa conflict with another key, this column would also display a C. The binding will have the defaultcontext In Windows. If you wanted to change this, you could change the When field to theappropriate context (for example, Editing Text).

4. To save your changes and leave the Preferences dialog open, click Apply. To save your changesand close the Preferences dialog, click OK.

Note:If you wish to delete a binding, highlight the command and then either click Unbind Command orsimply give focus to the entry in the Binding field and remove it using the Backspace key.

Backing up your PreferencesYou can save your current Preferences to a backup file, and then re-import them if you want to go backto that particular set of Preferences at any time.

To save your preferences to a backup file, proceed as follows:

1. Select File ➤ Export… ➤ General ➤ Preferences.

2. Click Next.3. The Export Preferences dialog is displayed:


88

4. Ensure that WPS Preferences and/or Keys Preferences (refer to Shortcut Key Preferences) isticked.

5. Using the Browse button next to the To preference file field, specify either the name of a newbackup preference file (the file will automatically be created with an extension of .epf), or the nameof an existing backup file with an extension of .epf.

Note:If you specify the name of an existing file, then, if you do not wish to be warned when you are aboutto overwrite it, select Overwrite existing files without warning.

6. Click Finish to complete the creation of the backup file.

To re-import preferences from a backup file, proceed as follows:

1. Select File ➤ Import… ➤ General ➤ Preferences.

2. Click Next.


89

3. The Import Preferences dialog is displayed:

4. Ensure that WPS Preferences and/or Keys Preferences (refer to Shortcut Key Preferences) isticked.

5. Using the Browse button next to the From preference file field, specify the name of the existingbackup file to be imported (it will have an extension of .epf).

6. Click Finish.


90

Creating a new programYou can create a new program under either the Project Explorer or File Explorer. Refer toCreating anew program file in a project or Creating a new program file in a file system, respectively.

You can then create and edit the program in the Workbench using the SAS Editor and the Text-basedediting features.

Note:To assist in navigation, the Workbench displays the structural elements of a program in the Outline(of structural elements).

Tip:If you are new to programs written in the SAS language, it may be advisable to look first at theprograms in the sample project if you have not already imported them (refer to Importing the sampleand other projects). These will give you an idea of syntax and the use of datasets.

Once you have your emply program file open in the SAS Editor, proceed as follows:

1. Enter the code. The folllowing example shows you how to create a simple dataset of employees:

/* Create a dataset */ DATA employees; LENGTH Name $10 Age 3 Job $15; INPUT Name $ Age Job $; /* Here is the data */ CARDS; Beth 41 Sales-Manager Steve 32 Sales William 35 Accounts Anne 28 Marketing Dawn 26 Sales Andrew 36 Support ;

2. Save your program by either typing Ctrl + S or selecting File ➤ Save.

3. Make any edits as required, referring as required to the Text-based editing features. The Workbenchdisplays the language elements in the program using colour coding to help you to see the structureof the code. Some of the default colours used are green for comments, blue for keywords, and ayellow background for data lines, for example:


91

The colour coding also helps you to see if you have made a typing error with language elements.For example, in the sample program, change the word DATA on the second line to DAT and youshould see it is displayed in red.

Note:Ensure you undo this typing mistake (by either typing Ctrl + Z or selecting Edit ➤ Undo Typing onyour keyboard) before continuing.

Important:If your program is not displaying any colour coding, then this is likely to be because it does not havean extension of either .wps or .sas. Without such an extension, it will not be able to be executed.

4. Run the program in accordance with Running a program from inside the Workbench.

Any datasets that are generated, as is the case with the above example, are created in the Worklocation under Libraries, and can be edited in accordance with Editing a dataset.


92

Note:For the remainder of the program output, refer to Working with program output.

WPS Syntax ColouringThe Syntax Colouring dialog under Window ➤ Preferences… ➤ WPS ➤ Syntax Colouring allows youto specify how to display the language items contained in a program (data lines, comments, formats,and so on):


93

For each different type of language item, you can specify attributes relating to Color, BackgroundColor and whether the item should be displayed in Bold orItalic.

Entering WPS code via templatesYou can select Window ➤ Preferences… ➤ WPS ➤ Code Templates in order to define templates thatcan be entered as code shortcuts into programs. These templates can be accessed through the normalcode completion key sequence (typically, CTRL + Space). For example if you define a code templatewith the name template1, you can type temp followed by CTRL + space and the code completionfeature will execute the following actions:

1. Match temp against the list of code templates.2. Find your template called template1.3. Enter the Pattern associated with the template into your program.


94

If there is more than one code template whose name starts with temp, then you will be presented with adialog to allow you to select the template to be used.

The Pattern containing the code to be entered into your program can be as simple or as complex asyou like. It could just be a single word. For example, you could define a code template to expand to thename of a frequently used dataset for which the name is difficult to type. A code template could alsodefine a large amount of text, for example, a boilerplate invocation of a particular procedure.

Note:If you are entering a variable into a Pattern, then it needs to be enclosed within pairs of '$$' characters.

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

Dynamic Help for Language ElementsThe 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 (refer to Onlinehelp), press F1 on your keyboard to open it.

2. As you type in a new word, or point to an existing word within a program, then, as soon as theWorkbench thinks it recognises it, the Help view will automatically build a search term to useto search the WPS Reference For Language Elements guide. The search appears in the Moreresults: section of the current help topic.

3. Click on the search term to perform the search. Relevant topics will be listed in the Help view toassist you with writing your program.

4. When you have finished reading the help, click on the Related Topics link (on the top right ofthe Help view) to return to the context-sensitive help page (otherwise, the view will not be updatedautomatically as you continue to use the Workbench).

Using Program Content AssistThe SAS Editor provides a content assistance feature that suggests language elements. When youselect these elements, they are automatically entered into your program. Proceed as follows to selectone:

1. Type a word into a program that may be associated with language elements.

For example, type the word PROC.2. After the word, type a single space character.


95

3. Now press CTRL + SPACEBAR.

If there are any expected language elements after the word you typed in step 1, then a popup list isdisplayed of these elements.

4. (Optional) You can filter the list by typing in the first letter(s) of the language element that you thinkyou may want to use.

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

WPS Code InjectionYou can select Window ➤ Preferences… ➤ WPS ➤ Code Injection in order to enter code that is to beexecuted automatically immediately prior to the running of a program, and/or immediately following therunning of a program.

Enable custom pre-code injectionWhen this option is enabled, the code in the associated text box is executed immediately prior tothe running of a program. This option provides a facility similar to the INITSTMT option describedin WPS Reference for Language Elements, except that, here, the code is automatically runbefore each program that is submitted (the INITSTMT system option is only processed on serverstartup).

The setting Automatically Manage Result Types in the Result Options Preferences allows youto select the automatic creation of ODS destinations (so that you can, for example, easily viewthe results of your programs in HTML and PDF). However, the automatic creation of destinationsmay not be suitable for you, and, in this case, you can use the custom code injection facility to setup ODS destinations in a more suitable way.

Enable custom post-code injectionWhen this option is enabled, the code in the associated text box is executed immediatelyfollowing the running of a program. This option provides a facility similar to the TERMSTMT systemoption described in WPS Reference for Language Elements, except that, here, the code isautomatically run after each program that is submitted. The TERMSTMT system option is onlyprocessed on server shutdown.

Code AnalyserYou can use the Workbench Code Analyser to scan the code of existing programs written in the SASlanguage.

The Code Analyser is a feature of the Workbench and can therefore only be used on platforms onwhich Workbench is supported. The Code Analyser generates reports that indicate which of yourexisting programs will run unchanged in WPS, which programs may require modification to run, andwhich programs contain language elements not yet supported by WPS.


96

The Code Analyser allows you to:

• Analyse Program Compatibility – whether your existing programs or projects contain anyunsupported language elements.

• Analyse Language Usage – lists language elements used in the selected programs or projects.The analysis indicates which elements are supported and which are not.

Running analysesThe Code Analyser can quickly analyse single programs, or all programs in multiple projects (using theProject Explorer) or folders (using the File Explorer).

Programs that might normally be executed on multiple different platforms can be analysed together.Gather the programs from these other environments, copy them to your workstation and then run theanalysis tools from Workbench.

Analysing program compatibilityYou can analyse one or more programs to identify which contained language elements are supported inWPS.

To analyse SAS language programs:

1. Select the files to be analysed:

• Select the required file or files to analyse in the Project Explorer or File Explorer. You canhighlight programs in different projects or folders within the particular view.

• Select one or more projects in the Project Explorer to analyse all contained programs.• Select one or more folders in the File Explorer to analyse all contained programs.

2. In the view corresponding to your selection, right-click on the selected items and from the short cutmenu click Analyse, and then click Program Compatibility.

When the analysis has finished, a Program Compatibility Report automatically opens in theWorkbench.


97

This report contains details about unsupported language elements used in programs. It does not reporton any supported language elements that were used in the programs.

Analysing language usageYou can analyse one or more programs to identify supported language elements used in one or moreprograms.

To analyse SAS language programs:

1. Select the files to be analysed:

• Select the required file or files to analyse in the Project Explorer or File Explorer. You canhighlight programs in different projects or folders within the particular view.

• Select one or more projects in the Project Explorer to analyse all contained programs.• Select one or more folders in the File Explorer to analyse all contained programs.

2. In the view corresponding to your selection, right-click on the selected items and from the short cutmenu click Analyse, and then click Language Usage.

When the analysis has finished, a Language Usage Report automatically opens in the Workbench.


98

This report details the SAS language elements used in the selected programs, and you can explore thedetail of this report in the Workbench, or export the content to Microsoft Excel

Analysing mainframe programsThe Code Analyser is a feature of the Workbench and can therefore only be used on platforms onwhich Workbench is supported. To analyse programs designed to run on a mainframe, copy therequired programs from the mainframe to a workstation running the Workbench. When these programsare analysed, the Code Analyser will identify SAS language elements specific to the z/OS platform.

Before analysing programs copied from a mainframe to a workstation:

• We recommended you remove sequence numbers from your jobs.• Ensure each program file has a file extension of .sas• Package up the jobs on the mainframe using XMIT.• Once transferred to the workstation, use XMIT Manager to un-XMIT the jobs for analysis.

Note:XMIT Manager can only handle PDSs (Partitioned Datasets) and not PDSEs (Extended PartitionedDatasets).

When downloading the XMIT files from mainframe to your workstation, you must specify FB (FixedBlock) with an LRECL (Logical Record Length) of 80 and with no ASCII/EBCIDIC conversion, truncationor CRLF translation.


99

Viewing or exporting an analysis reportYou can view the detail of a Code Analyser report in Workbench, or export the report detail to MicrosoftExcel.

When viewing a report in Workbench, you can navigate to more detail, and ultimately to the sourceprogram where an issue is located.

• The program compatibility report summary links to a list of programs analysed. From this list youcan access a list of problem elements, see where those elements are used within a program, andnavigate to the element location within the file.

• The language usage report summary displays the SAS language elements used in the analysedprograms. From this list you can find the frequency of SAS language element usage, whichprograms contain the elements, and navigate to the element location within the file.

Exporting analysis results to Microsoft ExcelThe results of a program compatibility report or language usage report can be exported to a MicrosoftExcel spreadsheet for either further analysis or to preserve the report information. To export a report:

1. In the report summary page, click Export results to Excel.2. In the Save as window, enter the required name for the spreadsheet, and browse to the required

location before saving it.

Analysis restrictionsBecause of the nature of the SAS language, the result of the analysis cannot be guaranteed, andreports should be treated as a guide for further analysis.

The Code Analyser has some limitations:

• The Code Analyser will not report incorrect syntax.• SAS language elements that are not currently supported in WPS are now shown in the Compatibility

Report as unknown.• The analysis reports do not currently contain information about the use of macro language elements

and library engine (data access) elements. Their use is however supported in WPS.


100

Working with editorsIn any of the Perspectives supplied with the Workbench or that you have created, the Editor window isalways displayed so that you can continue to write and modify files. In this section of the guide we willlook at the various ways of opening files into this window with the different editors.

Note:Only one file can be active at any one time. This is the file that currently has focus within the Editor.

You can open programs using either the Project Explorer or File Explorer. The Project Explorer offersmore control than the File Explorer, which determines the most suitable editor automatically, based onthe filename extension of the file being opened.

Editing files within Projects allows you to use Local history to help you manage changes, andalso provides the navigation and editing tools described under Text-based editing features.

SAS EditorThe SAS Editor provides features suitable for editing SAS programs, such as WPS syntax colouring.Only files with an extension .wps or .sas can be opened in this editor.

Programs can be opened either via a project or directly from one of the available file systems. Programsopened from a project allow additional Workbench features to be accessed by local history.

To open a program in the SAS Editor:

1. If your program belongs to a project, ensure that you have the Project Explorer open(Window ➤ Show View ➤ Project Explorer).

2. Navigate to the program you wish to open.3. Either double-click on the program that you wish to open, or right-click on it, and, from the

context menu, select Open With ➤ SAS Editor.

Note:If your program does not belong to a project, you can always drag the file onto the Workbench fromthe operating system's file system explorer, or any other appropriate external tool. You can also usethe File ➤ Open File... menu option.

The program is opened in the SAS Editor. The program assistance features described in Text-basedediting features are available.


101

Text EditorThe Workbench has a basic Text Editor.

Note:You can open a program with this editor but the contents will be treated as regular text - that is to say,no features are available for colour coding and so on.

To open a file in the Text Editor:


2. Navigate to the file you wish to open.3. If the file is a text file, then simply double-click on it. Otherwise, right-click on the file, and, from the

context menu, select Open With ➤ Text Editor.

The file is opened in the Text Editor. Most of the program assistance features described in Text-basedediting features are available.

System EditorIf a file has an extension associated with an application installed on your computer (for example, .docmay be associated with Microsoft Word), then the System Editor will launch that application with the filein a new window outside the Workbench.

To open a file with the System Editor:


2. Navigate to the file you wish to open.3. Provided that the file is associated with a particular application, then right-click on the file, and, from

the context menu, select Open With ➤ System Editor.

Note:If you wish to open the file with an application other than the one with which it is routinelyassociated, then select Open With ➤ Other... and then select an internal editor or an externalprogram from the resultant dialog.

The file is opened in a new window outside the Workbench, within the particular application.


102

In-Place EditorThe Workbench supports OLE (Object Linking and Embedding) document editing. For example, if youhave a Microsoft Word document in your project and use the In-Place Editor, the Word document willopen in the Workbench's Editor, with Microsoft Word's pull-down menu options being integrated into themenu bar of the view.

To open a file with the In-Place Editor:


2. Navigate to the file you wish to open.3. Right-click on the required file, and, from the context menu, select Open With ➤ In-Place

Editor.

Provided that there is an OLE editor associated with the selected file, the program is opened in theIn-Place Editor within the Editor. The menus and options associated with the linked application areavailable.

Default EditorWhen you simply double-click on a file, rather than making a selection from the context menu, theWorkbench opens the file using the editor last used to open that type of file, or, in the case of a new filetype, the application associated with it.

Note:If you wish to open a file with an application other than the one with which it is routinely associated, thenselect Open With ➤ Other... and then select an internal editor or an external program from the resultantdialog.

To open a file with the Default Editor:


2. Ensure you can see the file you wish to open.3. Either double-click on the file, or right-click on the file and, from the context menu, select Open

With ➤ Default Editor.

The file is opened using the editor last used, or, failing that, in a new window outside the Workbench,within its associated application.


103

Text Editor PreferencesUnder Window ➤ Preferences… ➤ General ➤ Editors ➤ Text Editors you can determine howprograms are displayed in the SAS Editor, and how files are displayed in the Text Editor. For example,if you wish to set the background colour, go to the Appearance colour options panel in the TextEditors dialog, highlight Background colour, untick System Default, and then select the requiredcolour via the Colour box.

Note:These Preferences only apply to files opened within the Project Explorer.

Some of the Preferences that can be configured are:

• Undo history size (that is to say, the size of the 'undo' buffer in terms of the number of operationsable to be undone)

• Displayed tab width• Show line numbers• Colours (current line, foreground, background, and so on)

Note:Details about the colours used to display language elements in the SAS Editor are controlled via theWPS Syntax Colouring preferences.

Closing filesAny file that is opened in the Editor has a tab labelled with the file name. To stop displaying the file inthe Editor, do one of the following:



Note:If you wish to close all open files at once, select File ➤ Close All.


104

Text-based editing featuresYou can use the features described below within the SAS Editor to help you write and modify programs and other project files within the Editor.

Note:The same features are available within the Text Editor, with the exception of the Colour Coding ofLanguage Elements. The features described are not available when managing files through the FileExplorer.

Left hand bordersThe left hand borders are used to display different features:

• In the outer left grey border, you will see annotations.• In the inner left white border, you will see the expand and collapse controls for blocks of

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

AnnotationsThese can consist of the following displayed in the outer left grey border of a file:

• Bookmark anchors

• Task markers

• Search results

Quick difference indicatorsA quick difference indicator in the inner left white border of a program shows that something haschanged in that line of code since it was last saved:

• Indicates that a change has been made to the line of code.

Note:If you hover the mouse over this coloured block, a popup window will show you the code as it wasprior to the change.

• Indicates that there is a new, additional line of code.• Indicates the position where one or more lines of code have been deleted.

Note:When you save a program, the quick difference indicators will be cleared from the margin.


105

Navigating between annotations and quick difference indicatorsYou can navigate between annotations within an individual program by using the main menu optionsNavigate ➤ Next and Navigate ➤ Previous (or pressing the keyboard options CTRL + . andCTRL + , respectively).

As well as using these menu and keyboard options, you can also select Next Annotation and Previous Annotation on the Workbench's main button bar.

Note:Although Next Annotation and Previous Annotation would appear to imply that they arefor annotations only, you can actually use them to navigate between annotations and quick differenceindicators in any individual program that is open in the Editor view. To the right of each of the Nextand Previous annotation buttons in the main button bar are drop-down menus. You can usethese menus to select the markers and indicators between which you wish to navigate.

Layout preferencesThe display controls for a program, including the current line, foreground and background colours, andwhether to display line numbers, are user defined. Refer to the Text Editor Preferences section for moredetails.

Colour Coding of Language ElementsThe colours used to display language elements in a program can be controlled via the Preferencesrelated to WPS Syntax Colouring.

Bookmark anchorsA 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 File Explorer, unless they are members ofa project . This is because files opened outside of Projects may be anywhere in a file system on alocal or remote host, and bookmarks can only be set on files that are members of a workspace project.

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

You can list, and navigate between, all your bookmarks via the Bookmarks view ( Window ➤ ShowView ➤ Bookmarks).


106

To navigate between your bookmarks, refer to Jumping to a particular project location.

Note:If you export a project, the individual bookmarks are not exported with it.

Adding a bookmarkTo add a new bookmark on a particular line within a project file:

1. Open the program or file in the Editor.

2. Move your cursor into the far left grey border immediately to the left of the required line:

3. Either select Edit ➤ Add Bookmark from the menu, or right-click, and from the context menu, selectAdd Bookmark….

4. The Add Bookmark dialog is displayed, and you are prompted to enter a name for future reference.

The name defaults to the contents of the selected line.5. Either press Enter on your keyboard, or click OK, to complete the operation and close the dialog.

You will now see a bookmark tag in the border, and a corresponding entry in the Bookmarksview (if it is open). You can use this view while Jumping to a particular project location.

Note:You can add a bookmark to a whole file, by highlighting it within the Project Explorer, and thenselecting Edit ➤ Add Bookmark from the menu.


107

Deleting a bookmarkTo delete a bookmark:

1. Open the Bookmarks view ( Window ➤ Show View ➤ Bookmarks).

2. Right-click on the bookmark's description, and, from the context menu, select Delete.

3. You are prompted to select Yes to confirm the deletion.

Task markersA task marker represents a reminder about a work item.

Against any line within a program you can add a task and associate a short description and a prioritylevel of (High, Normal or Low). There is no limit to the number of task markers that you can add insidea program.

Note:It is not possible to create tasks on programs opened from the File Explorer, unless they are membersof a project. This is because programs opened in this way may be anywhere in a file system on alocal or remote host, and tasks can only be set on files that are members of a workspace project.

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

To navigate between your tasks, refer to Jumping to a particular project location.

Note:If you export a project, the individual tasks are not exported with it.

Adding a taskTo add a new task marker on a particular line within a program:

1. Open the program or file in the Editor.

2. Move your cursor into the far left grey border immediately to the left of the required line:


108

3. Right-click, and from the context menu, select Add Task….4. The Properties dialog is displayed, and you are prompted to enter a descritption for future

reference.

The description defaults to the contents of the selected line.5. Select the priority level (High, Normal or Low).6. Click OK, to complete the operation and close the dialog.

You will now see a task marker in the border, and a corresponding entry in the Tasks view (if it isopen).

Deleting a taskTo delete a task:

1. Open the Tasks view ( Window ➤ General ➤ Tasks).

2. Right-click on the task's description, and, from the context menu, select Delete.

3. You are prompted to select Yes to confirm the deletion.

Jumping to a particular project locationYou can jump to a particular location in a project file:

To jump to a bookmarked location:


109

1. Open the Bookmarks view ( Window ➤ Show View ➤ Bookmarks).

2. Either double-click on the required bookmark description, or right-click on it, and, from the contextmenu, select Go To.

3. The relevant file will then be opened (if it was closed), and the bookmarked line will be highlighted(or else the first line in the file if the entire file was bookmarked).

To jump to a task:

1. Open the Tasks view (Window ➤ Show View ➤ Tasks).

2. Either double-click on the required task description, or right-click on it, and, from the context menu,select Go To.

3. The relevant file will then be opened (if it was closed), and the line containing the task will behighlighted.

To jump to a particular line number:

1. Select Navigate ➤ Go to Line....

2. Enter the required number in the Go to Line dialog.3. Either press Enter on your keyboard, or click OK, to complete the operation and close the dialog.

To jump to the last edit:

1. Select Last Edit Location from either the toolbar or Navigate menu.

The relevant file will be opened (if it was closed), the last line you edited will be highlighted, and thecursor will be placed at the end of the last piece of text you edited.

Navigation between multiple projectfilesYou can have as many projects open in the 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. For eachprogram that is open, a corresponding tab is displayed. An open program can be given focus in theEditorwindow by clicking on its tab.

Moving backwards and forwards between programsThe main menu options Navigate ➤ Back and Navigate ➤ Forward (or and on thetoolbar) are analogous to the back and forward buttons on a web browser. However, unlike a webbrowser, when you close and re-open WPS Workbench, it still has the navigational information.

• Back navigates to the previous resource that was viewed in the Editorwindow.

• Forward displays the program that was active prior to selection of the previous Back command.


110

Searching and replacingYou can find any text string in an open program, as follows:

1. Ensure that the program to be searched is open in the File Explorer ( Window ➤ Show View ➤ File Explorer).

2. Display the Find/Replace dialog by either selecting Edit ➤ Find/Replace... from the menu, orpressing CTRL + F on your keyboard.

The Find/Replace dialog is displayed, which allows you to specify the term to be found, and, ifrequired, the term with which it is to be replaced.

Note:The default Scope is All, which means that the whole file is searched (you can amend this toSelected lines if required). The other options are those that you would expect to find in any searchdialog and are self-explanatory.

3. Click Find to find the first instance of the word and then proceed as required, clicking Find to moveto each new instance of the text string.

Note:If you select Close to remove the dialog, then the string is remembered, and selecting Edit ➤ FindNext and Edit ➤ Find Previous will conduct the same search, forwards and then backwards, withoutre-opening the dialog.

Undoing and redoing your editsThere is a multiple undo facility for project file edits, as follows:

1. Either select Edit ➤ Undo from the menu, or press CTRL + Z on your keyboard.

The last change you made is undone.2. Repeat the above step for each previous edit that you wish to undo.

Note:The number of undos that can be performed is determined by Undo history size in the Text EditorPreferences.

Note:You can also redo any undone edits on an incremental basis, by either selecting Edit ➤ Redofrom the menu, or pressing CTRL + Y on your keyboard, the requisite number of times.


111

LibrariesA library is used to store WPS data files (including datasets), as well as folder locations and databaseconnections via the LIBNAME statement.

On the majority of operating systems, a library maps directly to an operating system folder. Theoperating system folder may contain non-WPS files, but only the files with extensions that WPSrecognises will be visible in the Workbench.

The default Libraries that are set up under each server in WPS Server Explorer are as follows:

• SASHELP, a read-only library containing a variety of system metadata.• SASUSER, which allows you to store datasets and other information that you want to keep beyond

the end of your WPS session. Simply add sasuser. in front of the name of the relevant dataset inyour program.

• Work, which is where your datasets, catalogs and Filerefs are stored by default. Work is a'temporary working space' that is automatically cleared of all data when your WPS session ends. Itis generally defined by the Work definition in the wps.cfg file in the root of your WPS installation,and is typically set to be -WORK '!TEMP\WPS Temporary Data', where TEMP is a Windowsenvironmental variable that is typically defined to be a path on the C: drive.

Instead of changing the wps.cfg file, you could either set Work to be a non-temporary location,as described in Set WORK location, or use the LIBNAME statement to write any data that you wishto keep, to your own permanent location (that is to say, directory or database connection). TheLIBNAME statement assigns an alias to the specific location, and this is then used in subsequentprograms in place of the name of the directory or database connection.

Note:The maximum length of a LIBNAME alias is 8 characters.

Once a dataset has been stored in the desired location, the associated alias must be used toretrieve the dataset (without the alias, WPS would look in the default Work directory for thedataset). The following LIBNAME statement assigns the alias mylib to the /mydirectory/ shareddirectory:

LIBNAME mylib '/directories/mydirectory/';

Note:Any directory or database connection that you associate with the alias must already exist beforeyou assign it. For full details of the LIBNAME language element, refer to the WPS Reference ForLanguage Elements guide. Common LIBNAMES can be set up via an AutoExec file so that they donot need to be added to every program that is run.


112

As an alternative to using the LIBNAME statement, you can create a new library by either selectingNew WPS Data Library from the drop-down next to the New icon in the top left hand cornerof the Workbench window, or right-clicking on Libraries in WPS Server Explorer, and then selectingNew ➤ Library.

Set WORK locationProceed as follows to set the pathname for the Work location that is used every time you start up aparticular server:

1. In the WPS Server Explorer, Link Explorer, Output Explorer or Results Explorer, ensure that theserver is running.



window.6. Search for and/or scroll down to the Work option, and then double-click on it. The Startup Option

dialog then displays your selection.7. in the Value: field, enter the full pathname of your Work folder and then click OK. You will now

see the Work option and its associated value listed in the Startup System Options panel of theProperties dialog.

8. When you click OK on the Properties dialog, you will be prompted to restart the server to apply yourchanges.

Note:Any Work option defined in any external Configuration files will be ignored. You must set Work as aWorkbench startup option, as described above, in order for it to be used from inside the graphical userinterface. When using WPS in Command Line mode to run programs in batch mode, then the startupoption is ignored and the Work option in the external configuration file is used instead.

CatalogsA catalog is a file in which you can store different types of information (called catalog entries), forexample formats, informats, macros, and graphics output.


113

As an example, you could write a program to generate a catalog (FORMATS) in which to store PICTUREformats, and another one (SASMCR) in which to store SAS language macros:

proc format;

PICTURE beau 0-HIGH = '00 000 000.09' ; PICTURE beaul 0-HIGH = '00 000 000.09' ; run; proc catalog catalog = work.FORMATS; contents; run;

%macro setscalingfactor; %let SCALE=%sysget(SCALE); %if %length(&SCALE.)=0 %then %let SCALE=2;%mend setscalingfactor;

%macro test;%mend;

proc catalog catalog = work.SASMACR;contents;run;

Note:FORMATS and SASMCR are built into the product for the storage of formats and compiled macros,respectively. Although these catalogs are generated by default in the Work library, you can use theLIBNAME statement to write any catalogs that you wish to keep, to your own permanent directory. ThePICTURE statement allows you to create templates for printing numbers by defining a format that allowsfor special characters, such as leading zeros, decimal and comma punctuation, fill characters, prefixesand negative number representation. For full details of the FORMAT and CATALOG PROCS, and thePICTURE statement, consult the WPS Reference For Language Elements guide.

When you run the program, the catalogs are created under the Work folder:

To view the entries associated with the catalogs, right-click on them and select Properties.


114

DatasetsA dataset is a file created or imported by a WPS server, and stored in a library (refer to Libraries). Itcontains rows and columns, very much like a database table. These rows and columns are known,respectively, as observations and variables in WPS.

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

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

Table 1. Example Dataset

Order ID Item ID Quantity Unit Price

10001 47853 3 30.75

10001 23104 10 4.90

10002 62091 1 89.99

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

Importing datasetsIn addition to the datasets created by running programs, datasets can be created by importing datavia a WPS server from external files. Currently supported formats are:

• Delimited• Fixed Width• Microsoft Excel Spreadsheet Files

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

The Dataset Import Wizard allows you to configure the dataset as it is imported. It is not 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 Finish to accept all the defaults.

Caution:If you import a dataset with the same name as an existing one, you will overwrite it. A warning appearsin the wizard if this is going to happen, and you have the chance to change the name of the dataset youare creating.

When importing delimited files, the Workbench will attempt to establish automatically which delimiterhas been used. If this delimiter is not correct, you will have the option to change it and the preview willbe updated to reflect the output that will be generated.


115

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 modify 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 of Excel spreadsheet files is also possible via either of the following methods:

• Programatically using the XLSX or Excel engines. For example:

libname xlsxlib XLSX ‘myfile.xlsx’ HEADER=YES; DATA WORK.IMPORTED;Set xlsxlib.Sheet1;Run;

/* The above can be generated by the code below */PROC IMPORT FILE=’myfile.xlsx’ OUT=WORK.IMPORTED DBMS=XLSX;SHEET=Sheet1;Run;

Or

libname xlsxlib Excel ‘myfile.xls’ HEADER=YES msengine=ACE; DATA WORK.IMPORTED;Set xlslib.'Sheet1$'n;Run;

/* The above can be generated by the code below */PROC IMPORT FILE=’myfile.xls’ OUT=WORK.IMPORTED DBMS=Excel;SHEET=Sheet1;Run;

Note:You can also use xlsx suffixes with DBMS=Excel.

• Using the Dataset Import Wizard on Windows local servers (refer to Importing spreadsheet data).In this event, your PC uses the Excel engine (replicating the code used in the second exampleabove), and will therefore need to have the Microsoft ACE OLEDB engine installed in order to beable to read and write Excel files in the XLS or XLSX format.

Note:Users who already have Excel installed are likely to have this engine by default. Windows usersthat do not have Excel installed can download and install the Microsoft Access Database EngineRedistributable. Legacy (XLS) versions of Excel are also supported, and the Import/Export optionsare available if you have the JET driver installed. However, with the JET driver installed in isolation,you can only read files in XLS format.

Importing datasets from filesYou will need to have the WPS Server Explorer open to be able to complete this task.


116

To import files:

1. Right-click the local server and select Import Dataset.

The Dataset Import Wizard is launched.2. Click Change next to the From File text box.3. Browse to the file that you wish to import. Select it and click Open.

A preview of the resulting dataset is shown, for example:

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

5. Optional: You can change the name of the new dataset, and where it will be stored, using thecontrols displayed.


117

• Change the library in which you want to store your new dataset in by using the Library Namedrop-down.

• Change the name of the dataset from the default by editing the contents of the Member Namefield. If you use the name of an existing member, then that member will be overwritten with yournew data.

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

File Format Configuration OptionsDelimited The wizard tries to establish the delimiter being used in the file. You can override this

as required.Fixed Width The wizard tries to establish the column definitions, but you can also amend these

as required. You can define more columns by clicking in a blank area to 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 defaults to the import of the first available sheet in the workbook thatcontains data. If required, choose a different worksheet from the Whole Worksheetdrop list. Alternatively, you can select a Named Range from the drop list to use asthe data source for importing (if any are available).

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

headers. Examine the preview to determine this.9. Click Next to move to the last page of the wizard.

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

• You can change a column name by clicking on the column header in the preview and editing 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.

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

The new dataset is imported under the specified Library Name in the WPS Server Explorer.

Importing datasets from files using Copy and Paste

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


118

You can import datasets from files using copy and paste, either from Project Explorer, File Explorer orfrom outside of the Workbench using your operating system.

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

1. Highlight the file that you wish to import as a dataset.2. Either right-click on the file and select Copy, or use the relevant keyboard shortcut (for example

CTRL + C).3. Find the library into which you want to import your dataset, using the WPS Server Explorer.4. Either right-click the library and select Paste, or use the relevant keyboard shortcut (for example

CTRL + V).

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

See Importing datasets from files for more on how to use the wizard.

Importing datasets from files using Drag and Drop


You can import datasets from files using drag and drop, either from Project Explorer, File Explorer orfrom outside of the Workbench using your operating system.

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

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

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


Importing spreadsheet dataProvided that your PC has the Microsoft ACE OLEDB engine installed, you can use the Dataset ImportWizard to import range of cells directly from Excel spreadsheets in the XLS or XLSX format.

Important:Data imported will have the value it had when the spreadsheet was last saved. If cells are based onformulae, then these are not evaluated by the Workbench when the spreadsheet is opened, with thelast saved value in the sheet being used instead.


119

Importing datasets from cell ranges using Copy and Paste


You can import a range of cells directly from Microsoft Excel into a Workbench library, as follows:

1. Select the contiguous range in your Excel spreadsheet that you wish to import.2. Press the keyboard shortcut for Copy (for example CTRL + C).3. Find the library where you want to import the data and select it in WPS Server Explorer.4. Press the keyboard shortcut for Paste (for example CTRL + V).

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

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


Importing datasets from cell ranges using Drag and 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.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 are displayed.


Opening a datasetYou can open a dataset as follows:

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


120

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

3. Open the dataset in one of two ways:

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

Proceed in accordance with Working with the Dataset Viewer.

Working with the Dataset ViewerThe contents of a dataset are shown in a grid. The rows of the grid represent dataset observations, andthe columns represent dataset variables.

Tip:You can display labels in the column headers of a dataset that you are viewing in the Workbench. Referto Dataset Viewer Preferences for more details.

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.

If some of the datagrid columns are irrelevant for a task, you can hide them, and you can re-organisethe view by moving columns. Refer to Organising the dataset.

ModeA 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. You can switch between Browse and Edit modes byselecting Data ➤ Toggle Edit Mode - refer to Editing a dataset.

You can only open a WPS dataset, that is to say a WPD, in Edit mode, and only if nobody else has thesame dataset open for editing on another computer.

Dataset Viewer Preferences

Under Window ➤ Preferences… ➤ WPS ➤ Dataset Viewer you can toggle on or off the Show labelsfor column names option that determines whether or not labels rather than column names aredisplayed in the column headers of a dataset that is viewed in the Workbench.

Note:Toggling on this option assumes that you have already set labels for column names in your programs (some items such as N, MEAN and STD generate labels by default).


121

Editing a dataset

You can edit observations, and also add and delete them, if the dataset is in Edit mode.

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

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

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


122

You can make as many changes as you like, and abandon them if you wish to by cancelling them. Thechanges are not written back to the original dataset until they are saved, by selecting either File ➤ Savefrom the main menu, or Save from the dataset context menu.. At this point, modifications are made, andobservations are then deleted and added.

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

Modifying observations

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


123

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:

2. Edit the value in accordance with the type of variable:Variable Type DescriptionNumeric You will see the raw value in an edit box. You can simply overtype

this with a new value. If you want to see how the value currently inthe edit box will be appear as a formatted value, press Shift + F8and it will be shown as a tooltip.

Note:Missing values can be entered as text - refer to Missing values -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 overtyped with replacementvalues.

For more intuitive control over the edit, you can use thealternative edit control associated with each type. DATE valueshave a calendar, times have a time picker, and DATETIMEvalues have a DATETIME picker combination. Click on thebutton to the right of the in-place value and the appropriate editorwill appear.


124

Variable Type DescriptionString Raw string values can be edited in-place in the same way as

numbers. If you want to see how the value currently in the editbox will appear as a formatted value, press Shift + F8 and it willbe shown as a tooltip.

3. When you have completed your edits, either press the Enter key or click outside of the cell, tocomplete the edit. If the value you entered is different from the original saved value, then theobservation is considered to have been modified, and will be shown as such. It will appear in boldtype with an asterisk (*) next to the observation number in the left margin of the grid.

4. The changes have not actually been saved back to the original dataset at this point. To Save thechanges and write them back to the server, select either File ➤ Save from the main menu, or Savefrom the dataset context menu.

Deleting observations


To delete observations from a dataset:

1. Select the observation that you wish to delete by clicking on its observation number in the left handcolumn. If you wish to delete multiple observations, hold down the CTRL key while clicking on theobservation number of each one that you wish to delete.

The selected observations are highlighted.2. Select Delete Observation, from the Data main menu option, the toolbar, or the right-click menu

on the dataset.

A message appears asking you to either confirm the deletion or cancel it.3. Click Yes to confirm the deletion. The data in the cells will be lightly crossed out, and a minus

character (-) will appear next to the row numbers in the left margin, to indicate that the observationsare marked for deletion:


125


Adding observations


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

1. Select Add Observation, from the Data main menu option, the toolbar, or the right-click menuon the dataset.

2. 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 can now edit the newobservation in order to populate the variables as required.


Cancelling changes

You can cancel any changes that you have made but not yet saved.

1. Select Cancel edits, from the Data main menu option, the toolbar, or the right-click menu on thedataset.

The Confirm Cancel Edits dialog will appear.2. Click Yes to confirm.


126

3. Any unsaved edits that you have made are cancelled, returning the dataset to how it was before thechanges were made.

Missing values


You can set observation variables to missing by using the Set Missing option in the datagridcontext menu.

Note:When numeric variables are formatted as DATE, DATETIME or TIME, this is the only way to set thesevariables as missing.

1. Select the observation variable (cell) you want to set as missing.

Ensure that only one variable is selected. You cannot set several observation variables to missing ina single operation.

2. Right-click on the dataset to display the context menu.3. Select Set Missing.

4. The Workbench will respond to your command in one of two ways, depending on the variable type.Variable Type DescriptionNumeric The Set Missing Value dialog opens. If the observation variable

is already set to a missing value, then the current raw value isshown - otherwise, the missing value defaults to '.' (full stop).You can change the missing value by simply pressing the keythat corresponds to the value you want to set. This value canbe any of the following: . (full stop), ._ (full stop followed by anunderscore), and .A to .Z. Press Enter or click OK to completethe command. Press Escape or click Cancel to return to the gridwith the original value unchanged.

String String variables are simply set to a single space (' ') characterwhen this option is chosen, and no dialog appears.


Filtering a dataset

This is only possible on a dataset that is on a WPS server version 3.2 or later. (The version of yourserver is displayed in the Properties view when you select the server in the WPS Server Explorer.)


127

Filters can be applied to a dataset regardless of the mode in which it is opened.

You can filter the contents of the dataset by variable, so that you see only the data that you need.

Filters are cumulative. Therefore, if you filter on more than one variable, all the various filters will apply.You can cancel any of the filters at any time.

Note:It is still possible to add an observation to a dataset while a view is being filtered. The new observationwill be visible during editing, regardless of the contents of the filtered variables. As soon as the changesto the dataset are saved, any filters are applied, and so the new observation will disappear from view ifit no longer meets the active criteria.

To filter your dataset view:

1. Click the filter button below the variable heading for the column that you wish to filter.

The filter criteria menu is shown:

2. Select the criteria by which you wish to filter the view.

Depending on the variable and the criteria chosen, either the filter button is replaced by an 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.


128

Data Type CriteriaDATE,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,click the button to set the time component of the filter value.

Other numericor string

The expression for the filter is shown below the variable header. Enter the value orvalues necessary to complete the expression in the edit box. For example, to filteron 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 referencesection Dataset 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.5. Optional: You can clear the filter for a variable by clicking on the filter button again, and then

selecting Clear Filter.

As you apply and cancel filters, the dataset contents are updated automatically in accordance with thelatest set of criteria.

Dataset filter expressions

You can filter the data viewed in a dataset. The filter menu options are essentially shortcuts to preparinga filter expression to use when the server is queried for the dataset data.

If the observation on which the filter is based is not a DATE, DATETIME or TIME formatted variable,you can edit the filter expression that is generated. Choosing to filter on these variables from the menuwill start the expression, and leave the cursor ready for you to enter a value to filter by, if one is needed.You can then amend this filter by clicking on the expression and editing it.

Note:You cannot edit the expressions of DATE, DATETIME or TIME variable filters. These can only becleared and re-entered.

The table below shows the editable expression syntax that is available from the filter menu.

Filter Expression SyntaxCriteria Expression Examples

Equal to EQ x or EQ s Is equal to 100 (numeric)

EQ 100


129

Criteria Expression ExamplesIs equal to "Blanco" (string)

EQ "Blanco"

Not equalto

NE x or NE s Is not equal to 100 (numeric)

NE 100

Is not equal to "Blanco" (string)

NE "Blanco"

Less than LT x Is less than 100

LT 100

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 "Blanco", "Jones" or "Smith"

IN ("Blanco","Jones","Smith")

Starts with LIKE " s% " Starts with the string "Bla"

LIKE "Bla%"

Ends with LIKE "%s " Ends with the string "nco"

LIKE "%nco"


130

Criteria Expression Examples

Contains LIKE "%s% " Contains the string "an"

LIKE "%an%"

Sorting a dataset

This is only possible on a dataset that is on a WPS server version 3.2 or later. (The version of yourserver is displayed in the Properties view when you select the server in the WPS Server Explorer.)

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

You can sort the contents of a dataset on several variables. Variables that are part of an active 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 be displayed. Thisis because to go into Edit mode would require the entire dataset to be rewritten in accordance with thecurrent sort order, to allow it to be edited in-place. If you require this, click Yes in the dialog, but youmust be aware that this will re-write the entire dataset on the server in the order you have set in thegrid, and put the grid into Edit mode. If you do not required this, click No.

You can sort a dataset as follows:

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

The column header menu will appear.2. Click on either Ascending Sort or Descending Sort to perform the sort.

The grid data is now sorted in the order requested.3. Optional: You can now add secondary and subsequent keys to the sort by following the steps above.4. Optional: You can clear any of the sorts by using the Clear Sort option from the context menu for

the associated variable.

Organising the dataset

You can manipulate the view of the dataset so that you hide variables you do not need, and movecolumns so that they are in a different order.

Note:These changes only affect your view of the data and do not affect the data itself.


131

Hiding variables

To hide a datagrid column:

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

The context menu appears.2. Click Hide column(s).

The datagrid column disappears from the view. If you attempt to hide a column for which filtering iscurrently active, then you will be asked to confirm that you wish to remove the filtering and hide thecolumn. Click Yes or No as appropriate.

Showing hidden variables

To show previously hidden dataset variables:

1. Right-click the dataset header row.

The context menu appears.2. Click Show / Hide Columns....

The Show / Hide Columns dialog appears, showing check boxes for the displayed columns (theseare ticked), and for the hidden columns (these are not ticked).

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

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

Moving columns

You can move columns to wherever you wish within the dataset view, regardless of the order of thecolumns in the actual dataset. Doing this will not change the physical order of the columns on theserver, only your current view of them.

To move a column:

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

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


132

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

The column appears in the new position.

Exporting datasetsWPS datasets can be exported under Windows as delimited and fixed width text, and also as MicrosoftExcel spreadsheets. 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.2. Right-click the dataset and select Export Dataset.

The Dataset Export Wizard is launched.3. Select Delimited, Fixed Width or Excel as required. For Excel, select which Excel format is to be

used, from the drop-down.

For Delimited or Fixed Width, the Export preview pane shows how the first few lines of the file willappear in the export.

4. Click Next.5. Optional: You can further configure Delimited and Fixed Width export. If you wish to include the

names of the columns, select the Include field names on first row check box. Further configurationoptions depend on the export type:Export Type OptionsDelimited Click on the delimiter of your choice, or click Other and type your own in the box

provided, if none of the standard delimiters are suitable.Fixed Width Alter the width of the columns by selecting the column in the drop-down, and editing

the Start and Width values.


133

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

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

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

Workbench cannot open the file, it will be opened in the appropriate application for your operatingsystem.

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 associated with the export file).

Clearing datasetsYou cannot just clear the datasets on their own. The process for clearing datasets unavoidablymeans that you also end up clearing all the other output, such as the HTML output, listing output, logentries, libraries, file references, and so on.

In order to clear all the output, proceed as in Restarting the server.


134

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

To see how you can control the output (datasets, logs, results, and so on) generated from the executionof a program on the selected server, refer to Working with program output. For details about some ofthe settings related to the running of programs, refer to WPS Preferences for running programs.

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

WPS Preferences for running programsTo control the general behaviour of WPS Workbench during program execution, make the appropriateselections from the following, under Window ➤ Preferences… ➤ WPS, before running any programs:

Save all modified files before running a programThis setting controls whether WPS will save any modified programs before a program is run. Thebehaviour can be one of : Always, Never or Prompt. The default is Prompt, which causes theSave and Run dialog to be displayed whenever you attempt to run a program that is not saved.

When you are editing a program and execute it using the Run button, it is the current contentof the editor window that is submitted, and not the contents of the file, and so if, for example,the setting is Never, these unsaved changes in the editor window will always be executed. TheSave and Run dialog gives you some control and allows you to switch the setting to Always(or Never) if you feel that this is more appropriate. For example, you might want to switch thesetting to Always if you have a program that is built up from several source files. You might haveone source file using an %INCLUDE statement to include the contents of the second, where the%INCLUDE statement reads the contents of the second file exactly as they appear on disk (andnot from the current content of the editor window). In this event, you would always want youredits to be saved to disk, to ensure that they are executed.

Close all open datasets before running a programThis setting controls how WPS deals with closing open datasets when running a program. Thebehaviour can be one of: Always, Never or Prompt. The default is Prompt, which causes theSave and Run dialog to be displayed whenever you attempt to run a program when one or moredatasets is open.


135

Having a dataset open in the Dataset Viewer (refer to Working with the Dataset Viewer) cancause problems if you attempt to run a program that is going to overwrite this same open datasetwith a new version. For this reason, you may want to set this option to Always, to avoid suchproblems.

Show log when an error is encountered running a programThis setting controls whether WPS shows the log file when an error is encountered in a program.The behaviour can be one of: Always, Never or Prompt. The default for this option is Promptwhich causes the Confirm Log Display dialog to be shown the first time an error is encounteredduring the running of a program.

If you leave Remember my decision ticked, then:

• Selecting Yes in the Confirm Log Display dialog will cause the setting to switch to Always,so that the log is shown automatically whenever there is an error.

• Selecting No in the Confirm Log Display dialog will cause the setting to switch to Never, sothat the log is not shown automatically whenever there is an error.

Close all open datasets when deassigning a libraryThis setting controls whether WPS automatically closes any datasets that may be open in alibrary when you deassign a library by selecting the Delete item from the context menu in the

WPS Server Explorer. The behaviour can be one of: Always or Prompt. The default for thisoption is Prompt which causes a dialog to be displayed when you attempt to deassign a librarywith open datasets.

Confirm deletionsThis setting controls whether or not WPS asks for confirmation when you use the Delete itemfrom the context menu in the WPS Server Explorer to take one of the following actions:

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

Confirm server restartThis setting controls whether or not WPS asks for confirmation when you select a server in the

WPS Server Explorer and then select Restart from the context menu.

Autoscroll the logThis setting controls whether or not WPS automatically scrolls the log output (refer to Viewing thelog).

Autoscroll the listingThis setting controls whether or not WPS automatically scroll the listing output (refer to Viewingthe listing output).


136

Show advanced server actionsThis setting controls the context menu options available when restarting WPS servers (refer toRestarting with Advanced Server Actions).

Temporary file locationThis field points to the directory where the Workbench stores temporary files. The log filescreated during execution of a program are stored in this directory, as are any ODS HTML resultsgenerated by programs.

You should be aware that output files, particularly logs, can be sizeable, and so may find that youneed to modify this setting if the field points by default to a location with space restrictions.

Note:You may also wish to set Always Run in Background (refer to General Preferences) if you are goingto be running programs that take a long time to execute.

Running a program from inside theWorkbenchThe 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 be executed until the other program has been completed. You may, however, register more thanone WPS server, in which case you can have more than one program running concurrently.

To run a program from inside the Workbench:

1. Ensure that the Code Submission option is set appropriately on the server (refer to Local WPSserver properties or Remote WPS server properties as appropriate).

2. Select the program you want to run by using one of the following methods:

• Highlight the program to be run in either the Project Explorer or File Explorer.

• Ensure that the program to be run is open in the Editor and is active.

Note:If the program was already open and you have part of the program highlighted, then the selectedpart will be executed (not the whole program).

3. Execute the program by doing one of the following:

• Use the CTRL + R keyboard shortcut to run the program on the default WPS server.• From the toolbar, click the button to run the program on the default server, or click the drop-

down next to this button to select a non-default server.

• From the main menu, select WPS ➤ Run File <pathname> ➤ Local Server (or substitutethe name of your remote WPS server in place of Local Server).


137

• From the program's context menu, select Run On ➤ Local Server (or substitute the name ofyour remote WPS server in place of Local Server).

When the program is run, an Executing window opens (unless Always Run in Background isselected), and its progress is indicated in the bottom right hand corner of the Workbench.

When you run a program, the state from previous executions is preserved, so that subsequentexecutions can interact with the datasets, Filerefs, and so on, that have been previously created.

In order to clear previous output on a given WPS server, select, from either the WPS menu ortoolbar, Clear Log ➤ Local Server (or substitute the name of your remote WPS server in placeof Local Server), or Clear Results ➤ Local Server (or substitute the name of your remoteWPS server in place of Local Server).

Alternatively, to clear the state of a WPS server completely, thereby emptying the Work library andde-assigning all of the macro definitions and libraries, then either select WPS ➤ Restart Server ➤ Local Server (or substitute the name of your remote WPS server in place of Local Server), orright-click the server in WPS Server Explorer and select Restart. Refer to Restarting the server.

Running part of a programYou can execute a particular part of a program as follows:

1. Ensure that the relevant program is open and active.

2. Highlight the section of code within the program that you wish to execute.

3. Execute the portion of code by doing one of the following:

• Use the CTRL + R keyboard shortcut to run the code on the default server.• From the toolbar, click the button to run the code on the default server, or click the drop-down

next to this button to select a non-default server.

• From the main menu, select WPS ➤ Run selected code from <pathname> ➤ Local Server(or substitute the name of your remote WPS server in place of Local Server).

• From the program's context menu, select Run On ➤ Local Server (or substitute the name ofyour remote WPS server in place of Local Server).

• Right-click in the Editor and select Run On ➤ Local Server (or substitute the name of yourremote WPS server in place of Local Server).

While the program is being executed, its progress is indicated in the bottom right hand corner ofthe Workbench.


138

Stopping an executionIf a program is running and you want to stop it before it has finished executing, proceed as follows:

1. From the main menu, either select WPS ➤ Cancel ➤ Local Server (or substitute the nameof your remote WPS server in place of Local Server), or click in the Progress view.

2. Once the progress indicator in the lower right corner of the Workbench disappears, this indicatesthat the program has stopped running.

Note:Depending on the particular step that the program is executing, the program may not stop immediatelyafter you try and stop it.

The log will contain a message similar to ERROR: Execution was cancelled.

WPS in Command Line modeBesides being able to use WPS in Workbench mode (that is to say, from the graphical user interface),you can also use it in Command Line mode, where it is referred to as wps. This provides a way ofrunning programs outside of the Workbench, which is also referred to as running in 'batch mode'.

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

To use WPS from a command line, you need to execute wps.exe (or simply wps) on Windows, orwps on any of the UNIX-based platforms. This executable file is located in the bin directory of yourWPS installation, and so you should switch to this directory first. Refer to Running a program from thecommand line of a Windows platform and Running a program from the command line of a non-Windowsplatform for examples.

OptionsRunning wps.exe or wps on its own will not do anything, and so you will need to pass some additionalinstructions in the following form:

wps.exe <options> <programFileName>

The <options> that are called from the command line can be a list of any of the following:

• -optionname [optionalValue]

• -config <configFileName>

• -set <envVarName> <envVarValue>


139

Note:When you run a program using wps.exe or wps, the <programFileName> must always be the lastparameter you define. (When wps is executed, the first parameter that is encountered which does notstart with a dash (-) is taken as the name of the program to run.)

The WPS compiler/interpreter is invoked directly. The files from the Results output cannot be seeninside the Workbench, unless the resulting files are opened manually inside it.

System optionsTo set a system option explicitly, specify:

wps.exe -optionname [optionalValue] <programFileName>

Note:You can pass as many optionname system options to wps as you wish. However, you can only passwps single value options. The command line does not allow parentheses. You can quote values withspaces in, but the quotes will be removed.

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

wps.exe -config <configFileName> <programFileName>

Refer to the Configuration files section for a more detailed discussion about configuration files and theorder in which they are processed.

Important:When running programs using wps, any WPS server properties that have been set up as preferencesunder the graphical user interface, are ignored.

Environment variablesTo set an environment variable to use with wps:

wps.exe -set <envVarName> <envVarValue> <programFileName>

You can set as many environment variables as you want but remember that, as above, wps only allowssingle values in the command line, and it does not allow parentheses.

Log outputWhen you run a program with wps, the log information about the run is automatically sent to thecommand window in which WPS is running. Once the program has finished running and this windowcloses, then this log information is lost. To capture this log information in Windows and non-Windowsenvironments (optionally using batch files and shell scripts, respectively), refer to Running a program


140

from the command line of a Windows platform and Running a program from the command line of a non-Windows platform.

Results outputWhen a program is run using wps, any results generated by the program are automatically capturedinto a file called <programFileName>.lst created in the same directory as the program. For example,a file called Program1.lst will be output if you run a program called Program1.sas. You can open theresults file with the text editor of your choice.

Running a program from the command line of aWindows platformRefer to WPS in Command Line mode for details about the <options> that can be specified.

ExampleLet us assume that you wish to run a program called Program1.sas located in the directory D:\Work\WPS Programs. Open a command window and change to the \bin directory of the WPS installation,and then, following the prompt, enter the following command:

wps.exe "D:\Work\WPS Programs\Program1.sas"

Creating a batch file to call WPSIf you wish to be able to run one or more programs using the same options each time, then it isadvisable to create a batch file to do this for you.

For example, if WPS is installed in C:\Program Files\World Programming WPS 3, and yourprogram is located in directory d:\Work\WPS Programs, then you could create a batch file calledRunPrograms.bat containing the following lines:

set WPSLOC=C:\Program Files\World Programming WPS 3set PRJLOC="D:\Work\WPS Programs""%WPSLOC%\bin\wps" "%PRJLOC%\Program1.sas"

Note:Ensure that absolute (fully qualified) paths are specified so that they can be executed from anywhere onyour machine and still work.


141

Including log file output in the batch fileWhen running wps, it is useful to capture the log information so that you can verify whether any errorsor problems were encountered. To do this, redirect the output of the program to a file. For example, tomodify the above example to redirect the output to a file called Program1.log, change the examplecode 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 openedwith the text editor of your choice.

Every time that you capture the log information into a file with the same name, the file will be recreated.In other words, log information is not appended to the same file - it only shows details from the latestrun. If you do require the new log to be appended, change the redirection symbol > to >>, for example:

"%WPSLOC%\bin\wps" "%PRJLOC%\Program1.sas" >> "d:\Work\WPS Logs\Program1.log"

Tip:Because log files can be too large to scan with the human eye to find individual errors, a simple searchfor error will verify whether or not the program was executed correctly.

Running a program from the command line of anon-Windows platformRefer to WPS in Command Line mode for details about the <options> that can be specified.

ExampleLet us assume that you wish to run a program called Program1.sas located in the directory /home/user/programs. Open a command window and change to the /bin directory of the WPS installation,and then enter the following command:

wps "/home/user/programs/Program1.sas"

Creating a shell script to call WPSIf you wish to be able to run one or more programs using the same options each time, then it isadvisable to create a shell script to do this for you.


142

For example, if WPS is installed in the directory /tools/wps and your program is located in directory/home/user/programs, then you could create a script called RunPrograms.sh containing thefollowing lines:

export WPSLOC=/tools/wpsexport PRJLOC=/home/user/programs"$WPSLOC/bin/wps" "$PRJLOC/Program1.sas"

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

Including log file output in the shell scriptWhen running wps, it is useful to capture the log information so that you can verify whether any errorsor problems were encountered. To do this, redirect the output of the program to a file. For example, tomodify the above example to redirect the output to a file called Program1.log, change the examplecode to:

export WPSLOC=/tools/wpsexport PRJLOC=/home/user/programs"$WPSLOC/bin/wps" "$PRJLOC/Program1.sas" > "/home/user/logs/Program1.log"

Once the shell script is run, the file Program1.log will be in the specified directory and can be openedwith the text editor of your choice.

Every time that you capture the log information into a file with the same name, the file will be recreated.In other words, log information is not appended to the same file - it only shows details from the latestrun. If you do require the new log to be appended, change the redirection symbol > to >>, for example:

"$WPSLOC/bin/wps" "$PRJLOC/Program1.sas" >> "/home/user/logs/Program1.log"

Tip:Because log files can be too large to scan with the human eye to find individual errors, a simple searchfor error will verify whether or not the program was executed correctly.


143

Working with program outputOutput from programs is generated in the following views:

• WPS Server Explorer - Provides access to the datasets, catalogs, Filerefs, and so on,that have been generated under the relevant libaries (for example, the default Work library) for theparticular server. Refer also to Dataset generation.

• Output Explorer - Provides access to the listing output, HTML output, PDF output and logs generated by the Workbench's ODS (Output Delivery System).

• Results Explorer - Provides access to hierarchical lists of the listing output, HTML outputand PDF output.

• Outline (of structural elements) - Provides access to the structural elements from the programs,logs, listing and HTML that have been output. If you click on a structural element in this view, therelevant line in the particular output file will be highlighted.

Log output for a server is cumulative and, as such, shows information and errors from each programthat has been run during the current session. It can be cleared in accordance with Clearing the log.Listing output is also cumulative and shows the results of every program that has been executed duringthe current session. HTML output similarly shows the results of programs, but is not cumulative. Listingand HTML output can be cleared in accordance with Clearing the results output.

The server itself can also be restarted in accordance with Restarting the server. This will clearthe log as well as any listing and HTML output. It will also delete any temporary files and deassign alllibraries, datasets and macro variables, and so on, that may have been set up on the server.

Dataset generationIf your program produces or amends a dataset, then this can be viewed from the relevant library inWPS Server Explorer. For example, each time you run the following sample program, having amendedthe bookmarked line as required, the associated dataset is updated in the Work library:


144

Note:For more information about the use of libraries on a server, refer to Libraries. For details about viewingdatasets, and manually amending them as required, refer to Working with the Dataset Viewer.

To view the details associated with a particular dataset, right-click on the dataset in the above view andselect Properties.


145

Managing ODS outputOnce you have run a program that produces some output using the Workbench's ODS (Output DeliverySystem), you can view it in the Results Explorer. The ODS destinations (which can be thought of asoutput formats in the context of WPS Workbench), and the location of the output generated, can eitherbe managed yourself, using explicit ODS statements in your code, or left to the Workbench to manageautomatically.

Result Options PreferencesBy default, WPS controls results automatically, in accordance with the setup inWindow ➤ Preferences ➤ WPS ➤ Result Options:


146

The default Yes setting of Automatically Manage Result Types causes ODS destinations to becreated automatically, in accordance with the check boxes ticked in the Result Types panel (bothHTML and Text (LISTING) output, accessible via the Output Explorer, are set initially). WPS createsthe destinations by automatically injecting relevant ODS statements before and after each program issubmitted (these statements are shown in the log automatically if Show generated injected codein the log is selected). If you select PDF, then, the first time that you execute a program, the PDFdestination appears in the Output Explorer and Results Explorer.

Note:Even if automatic management is chosen, it is still possible to define custom ODS destinations usingexplicit ODS statements in your code. You can set up your own HTML and PDF output within theprogram code and/or via WPS Code Injection. For a PDF program code example, refer to PDF output.

If Automatically Manage Result Types is set to No, then no ODS destinations will be set up bydefault, and all the output from running programs will be sent by default to the Text (LISTING)destination. This behaviour reflects what happens when you run WPS in Command Line mode, whichrequires programs to control their own ODS destinations.

LogsThis section of the guide looks at the management of the log output that is displayed in the Output Explorer.

Note:If you have more than one WPS server registered in the Workbench, then a separate log is available foreach server in the Output Explorer.

Log Colouring PreferencesThe preferences that you can set regarding the different items contained in a log file (errors, notes,warnings, and so on) are found under Window ➤ Preferences… ➤ WPS ➤ Log Syntax Coloring:


147

For each different type of item contained in a log, you can specify attributes for Colour, BackgroundColour, and whether or not the item should be displayed in Bold.

Viewing the logTo display the information contained in the log:

1. Ensure that you have the Output Explorer open ( Window ➤ Show View ➤ OutputExplorer).

2. If there is more than one server, open the required server node to display the associated log.3. Either double-click the Log node, or right-click it and select Open from the context menu.

The log opens and is given focus.


148

If you have performed several runs of a program, the previous log information will be concatenated intothe existing log text. If you wish to clear the log, to ensure that when you next run a program the logonly contains information for that run, then you can proceed in accordance with either of the following:

• Clearing the log.

• Restarting the server (which will clear the log and all results, datasets, library and Filerefs).

If the log contains a large amount of information, refer to Navigating the log.

Tip:You can control how the different items (errors, notes, warnings, and so on) are displayed in a log.Refer to Log Colouring Preferences.

Navigating the logIf you have executed several programs, or several instances of the same program, and have notcleared the log for the particular server by either Clearing the log or Restarting the server, theneach instance of output will have been appended to the log in order of execution.

To navigate the information contained in the log file:

1. Open the log in accordance with Viewing the log.2. Ensure that you have the Outline view open (Window ➤ Show View ➤ Outline).

3. In this view you will see nodes for all the previous log entries with the times at which they werecreated. You may also see error or warning nodes. Click on any of these nodes and thecorresponding section in the log file will be displayed.

Saving the log to a fileTo save the log to a file:



• Right-click on the Log node, and, from the context menu, select Save As....

• Open the log in the editor (see Viewing the log), and then right-click in the editor window andselect Save As….

• Open the log in the editor and then select File ➤ Save As... from the main menu.

3. Use the Save As dialog to save the file to the required location.


149

Printing the logTo print the log for a particular server:


2. If there is more than one server, open the required server node to display the associated output.3. Do one of the following:

• Right-click on the Log node, and, from the context menu, select Print Log....

• Open the log in the editor (see Viewing the log), and then right-click in the editor window andeither select Print… or press Ctrl+P on Windows (Cmd-P on MacOS).

• Open the log in the editor and then select File ➤ Print... from the main menu.

4. Use the Print dialog to send the log to your required printer.

Clearing the log1. If you wish to save a log before clearing it, proceed as in Saving the log to a file.2. Clear the contents of the log for the required server by doing one of the following:

• From the main menu, select WPS ➤ Clear Log ➤ Local Server (or substitute the name ofyour remote WPS server in place of Local Server).

• Use the keyboard shortcut Ctrl + Alt + L to remove the log from the default server.

Note:If you have more than one WPS server registered, then the above action will clear the log for theDefault WPS server. If in doubt as to which is the default server, use the tooltip for the toolbarbutton to show which log will be cleared.

• From the toolbar, click to clear the log from the default server, or click the drop-down nextto this button to select a non-default server.

• Ensure that you have the Output Explorer open ( Window ➤ Show View ➤ OutputExplorer), right-click on the Log node for the required server, and from the context menu,select Clear Log.

The log file for the selected server will now be blank.

PDF outputThis section of the guide looks at the PDF output of results.

To set up the automatic management of PDF output, refer to Result Options Preferences.


150

The default settings for PDF output are as specified in the wps.cfg file (refer to Configuration files),and are as follows:

• -BOTTOMMARGIN 1cm

• -LEFTMARGIN 1cm

• -RIGHTMARGIN 1cm

• -TOPMARGIN 1cm

• -ORIENTATION portrait

The PAPERSIZE is determined automatically by the locale of WPS Workbench (refer to WPS serverLOCALE and ENCODING settings). It can be reset using unmanaged output (see below).

The startpage option, which determines whether or not the output from each PROC starts on a newpage, is not configurable inside WPS Workbench. It is initially set to STARTPAGE=yes in the ODSsoftware, which means that each PROC does start on a new page. The option can also be reset usingunmanaged output (see below).

You create unmanaged output by entering code directly into your programs, as per the example below:

options orientation=landscape;options papersize=A4;options topmargin=0.75in;options bottommargin=0.5in;options leftmargin=0.5in;options rightmargin=0.5in; ods pdf file="body.pdf" startpage=no; /* Startpage=no means that new pages are not generated between PROCs */ /* Insert PROCs to generate output */ ods_all_ close;

Note:Relevant parts of the code can also be used as WPS code injections.

Listing outputThis section of the guide looks at the listing output of results.

Listing Colouring PreferencesThe preferences that you can set regarding the different items contained in listing results are foundunder Window ➤ Preferences… ➤ WPS ➤ Listing Syntax Coloring:


151

For each different type of item contained in a listing, you can specify attributes for Colour, BackgroundColour, and whether or not the item should be displayed in Bold.

Viewing the listing outputTo view the listing output:

1. Ensure you have the Output Explorer open ( Window ➤ Show View ➤ Output Explorer).

2. If there is more than one server, open the required server node to display the associated output.3. Either double-click the Listing node, or right-click it and select Open from the context menu.

The listing output opens and is given focus.


152

If you have performed several runs, the previous listing output will be concatenated into the existingresults. If you wish to clear the output, to ensure that when you next run a program the listing onlycontains results for that run, then you can proceed in accordance with either of the following:

• Clearing the results output (which will also clear any HTML output).

• Restarting the server (which will clear the log and all results, datasets, library and Filerefs).

Navigating the listing outputIf you have executed several programs, or several instances of the same program, and have notcleared the results for the particular server by either Clearing the results output or Restarting theserver, then each instance of listing output will have been appended to the existing listing file in order ofexecution.

To navigate the output contained in the listing file:

1. Open the results in accordance with Viewing the listing output.2. Ensure that you have the Outline (of structural elements) view open ( Window ➤ Show View

➤ Outline).

3. In this view you will see nested output for the various programs, with nodes for the different outputelements. Click on any of these nodes and the corresponding section in the listing file will bedisplayed.

Saving the listing output to a fileTo save the listing output to a file:



• Right-click on the Listing node, and, from the context menu, select Save As....

• Open the listing in the editor (see Viewing the listing output), and then right-click in the editorwindow and select Save As….

• Open the listing in the editor and then select File ➤ Save As... from the main menu.

3. Use the Save As dialog to save the file to the required location.

Printing the listing outputTo print the listing output for a particular server:


153



• Right-click on the Listing node, and, from the context menu, select Print Results....

• Open the listing in the editor (see Viewing the listing output), and then right-click in the editorwindow and either select Print… or press Ctrl+P on Windows (Cmd-P on MacOS).

• Open the listing in the editor and then select File ➤ Print... from the main menu.

4. Use the Print dialog to send the results to your required printer.

HTML outputThis section of the guide looks at the HTML output of results.

Viewing the HTML outputTo view the HTML output:

1. Ensure you have the Output Explorer open ( Window ➤ Show View ➤ Output Explorer).

2. If there is more than one server, open the required server node to display the associated output.3. Either double-click the HTML node, or right-click it and select Open from the context menu.

The HTML output file opens and is given focus.

Navigating the HTML outputIf you opted to have the HTML output automatically managed by the Workbench (refer to ResultOptions Preferences), then each run will create a new HTML file. However, if you have executedseveral programs, or several instances of the same program, and have not cleared the results for theparticular server by either Clearing the results output or Restarting the server, then the previousHTML output will still be available in the Outline (of structural elements) view.

To navigate the output contained in the HTML file:

1. Open the results in accordance with Viewing the HTML output.2. Ensure that you have the Outline (of structural elements) view open ( Window ➤ Show View ➤

Outline).


154

3. In this view you will see nested output for the various programs, with nodes for the different outputelements. Click on any of these nodes and the corresponding section in the HTML output will bedisplayed.

Printing the HTML outputTo print the HTML output:



• Right-click on the HTML node, and, from the context menu, select Print Results....

• Open the HTML file in the editor (seeViewing the HTML output), and then right-click in the editorwindow and either select Print… or press Ctrl+P on Windows (Cmd-P on MacOS).

• Open the HTML file in the editor and then select File ➤ Print... from the main menu.

4. Use the Print dialog to send the results to your required printer.

Note:A single HTML output file is created for each run within the Workbench. However, you can only print theHTML output of one run at a time.

Clearing the results output1. If you wish to save your output before clearing it, save your PDF elsewhere if you have been using

the PDF destination, or proceed as in Saving the listing output to a file.

2. Clear the output results for the required server by doing one of the following:

• From the main menu, select WPS ➤ ➤ Clear Results ➤ Local Server (or substitute the nameof your remote WPS server in place of Local Server).

• Use the keyboard shortcut Ctrl + Alt + O to remove the results from the default server.

Note:If you have more than one WPS server registered, then the above action will clear the results forthe Default WPS server. If in doubt as to which is the default server, use the tooltip for the toolbarbutton to show which server's results will be cleared.

• From the toolbar, click to clear the results from the default server, or click the drop-down next to this button to select a non-default server.


155

• Ensure that you have the Output Explorer open ( Window ➤ Show View ➤ OutputExplorer), right-click on the listing output, HTML output or PDF output for the requiredserver, and from the context menu, select Clear All Results.

All output will now be blank.

Note:The effects of this option are different from Restarting the server in that you preserve the context ofwhat you are currently doing, and do not lose your temporary work.

Restarting the serverEach time that the Workbench is closed, the results associated with the session - the log, all the outputresults, the Filerefs, libraries and datasets, and so on - are cleared. However, if you wish to clear thesame things prior to the end of the Workbench session, then you can do so by restarting the WPSserver, as shown below.

Caution:Doing this means that programs will no longer be able to interact with any objects created prior to therestart of the server.

If you only wish to clear the log or results, and keep all the other output, then proceed as in Clearing thelog or Clearing the results output respectively.

Proceed as follows to restart the server:


• If it is the default WPS server that you are trying to restart, you can use the keyboard shortcut(this is Ctrl-Alt-S by default).

• From the main menu, select WPS ➤ Restart Server ➤ Local (or substitute the name of yourremote WPS server in place of Local).

• Right-click on the required server in the Link Explorer, WPS Server Explorer, ResultsExplorer, or Output Explorer, and select Restart from the context menu.

Note:If Show advanced server actions is enabled in WPS Preferences for running programspreferences, then the single Restart menu option will not be available. Refer to Restarting withAdvanced Server Actions below.

2. A confirmation window may be displayed, allowing you to cancel the restart if you wish. Click OKto clear everything - the log, all the output results, the Filerefs, libraries and datasets, and so on -for that server. (You will not see the confirmation dialog if you have previously checked the Do notshow this confirmation again option in the dialog.)


156

3. The datasets and Filerefs are removed from the WPS Server Explorer, the listing and HTMLresults are removed from the Output Explorer, and the associated log is cleared, and the links tothe results are removed from the Results Explorer.

Restarting with Advanced Server ActionsThis section is only relevant to users who have the Show advanced server actions option enabledin WPS Preferences. If this option is enabled, then, in the WPS server context menu in the WPSServer Explorer, Output Explorer, and Results Explorer, the following options are available forrestarting the server, instead of the single Restart option:

• Restart, new WORK - Restart and clear all the contents of the Work library (as for a normal restart).• Restart, keep WORK - Restart and keep all the contents of the Work library.


157

WPS Link client/server setupIf you have configured one or more remote connections and servers, then you should be aware thatthere are 3 items required for a WPS Link client/server setup: an SSH (Secure Shell) server, the WPSsoftware itself, and sufficient WPS licence keys to cover the setup.

SSH serverWPS Link requires the use of an SSH connection between the server and client machines. This is notsupplied with the WPS software. However:

• For a UNIX (Linux, Solaris or AIX) server machine, the built-in SSH daemon can be used.• For a Windows server machine, the third party SSH facility is available separately from Bitvise.

Note:Bitvise SSH is the only SSH facility officially supported by World Programming at present for aWindows server machine.

WPS softwareWPS is supplied as a single installation file that contains all the WPS features required for use withWPS Link, including WPS Workbench, the Java Runtime Environment, and the licensable WPS servercomponent.

You will need WPS installation files that are suitable for the operating systems on both server and clientmachines. For example, if you have a Linux server machine and Windows client machines, you willneed the Linux installation file for the server, and the appropriate Windows installation files (32-bit or 64-bit) for the clients. Refer to the relevant platform installation guide for full details of the WPS installationprocess.

WPS licence key(s)In order for a WPS installation to be able to execute a program written in the language of SAS, the WPSserver component component needs to be activated by the application of a WPS licence key (suppliedseparately to the WPS software - refer to Applying a licence key).

• If you want to restrict the execution of programs to the linked server, then you only need a licencekey for the server installation of WPS.

• If you want to be able to execute programs on either the client machine or the linked server, thenyou need separate licence keys for the server and the client installations of WPS.


158

Client/server installation summaryA brief overview of the sequence of steps required to install and set up a WPS Link client/serversolution is given below.

Important:The person who installs WPS and applies the licence keys must have operating system administratorprivileges on those machines.

1. Outside WPS, set up and test the SSH connection between the server and client machines inaccordance with the platforms and authentication methods that are active at your site (refer to theWPS Link user guide and reference for details).

2. Install WPS fully on the server machine if you are going to be executing programs on that machine.When you launch WPS on the server, you will automatically be prompted to apply the licence.

3. If you have not already done so, install WPS on the individual client machine(s). When you launchWPS on the client(s), you will automatically be prompted to apply the workstation licence.

Note:If you are only going to be running programs on the linked server, and you do not therefore requirea licensed installation of WPS on the client, then, provided that you are running Windows on theclient, you can isolate the WPS Local Server from the installation (refer to Configuring the localWPS installation).

4. Inside WPS, create a link to the remote computer in the following two-step operation:

a. Create a connection to the remote host (refer to Creating a new remote host connection).b. Add a WPS server to this remote host so that you can run your programs remotely (refer to

Defining a new WPS server).

Managing local and remote hostconnectionsThis section covers the connection properties of both local and remote hosts, including the creation ofdirectory shortcuts, and the import and export of connection definitions.

Tip:You can also create directory shortcuts in the File Explorer, by right-clicking on the required folder,selecting New ➤ Directory Shortcut, and then supplying the required shortcut name in the DirectoryName field of the Directory Shortcut dialog.


159

Local host connection properties (DirectoryShortcuts)These properties are accessed by selecting the Local host connection in the Link Explorer, and thenright-clicking and selecting Properties from the context menu. The only properties available for a Localhost connection are Directory Shortcuts.

A directory shortcut is a shortcut to a directory on the local file system. The local shortcuts that arecreated by default differ in accordance with the operating system on which you are running theWorkbench:

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

• Other operating systems. Only Home (~/) and Root (/) shortcuts are created by default.

To set up a new shortcut, click Add to display the following dialog:

After Directory Name, enter the shortcut name you want to use, and, after Directory Path, clickBrowse, select the required directory, and click OK. The shortcut name then appears in the host filesystem in File Explorer when the host connection is open. You can double-click a shortcut to changeits definition.

Other directory shortcuts can be edited as required, and removed from this property page.

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 administratorto obtain this information, and to ensure that you have access. For details of the means of SSHauthentication, refer to the WPS Link user guide and reference.

Proceed as follows to create a new remote host connection:

1. Launch the New Remote Host Connection wizard by doing either of the following:


160

• Ensure that you have the Link Explorer open ( Window ➤ Show View ➤ Link Explorer)open, and click New Remote Connection.

• From the main menu, select WPS ➤ Link ➤ New Remote Host Connection.

2. In the New Server Connection dialog, choose one of:

• New SSH Connection (3.1 Compatibility)• New SSH Connection (3.2 and later -- UNIX, MacOSX, Windows)

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

Note:You should be aware that, if you select 3.2 and later, and then subsequently revert to WPS Version3.1, you will lose any remote host connections that were set up in WPS Version 3.2.

3. Click Next and complete the following dialog:


161

• For Hostname, enter the name or IP address of the remote machine to which you wish toconnect.

• For Port, you can specify a port other than the default 22 if required, but, if so, you should verify itfirst with your system administrator.

• The Connection name defaults to the Hostname, but you can overwrite this to enter adescriptive name for the connection.

Remember:Connection names must be unique, so, if you are creating multiple connections to the same host,you will need to modify the Connection name each time.

• For User name, enter your user ID on the remote host.• In the last two check boxes, ensure that Open the connection now is ticked if the connection

is to be opened now, and that Open the connection automatically on Workbench startup isticked if the connection is to be opened automatically whenever WPS Workbench is started.

Tip:If you are going to be using the connection regularly, select Open the connection automaticallyon Workbench startup so that, once the associated server starts, the connection is alreadyopen.

4. Press Next to define the connection's directory shortcuts:


162

A directory shortcut is a shortcut to a path on the host's file system. By default, there are directoryshortcut defined for Home (~/) and Root (/). To set up a new shortcut, click Add to display thefollowing dialog:

After Directory Name, enter the shortcut name you want to use, and, after Directory Path, thefull path (as shown when you hover over the location in File Explorer), and click OK. The shortcutname then appears in the host file system in File Explorer. You can double-click a shortcut tochange its definition.

5. Click Finish. If you have not previously validated the authenticity of the remote host, an SSH2Message dialog of the following kind shown is displayed:


163

If you are certain that the identity of the host is correct, click Yes. If you are setting this up in aproduction environment, you should explicitly confirm with a system administrator that the displayedRSA key fingerprint of the remote host matches that of the host to which you intend to connect.Once the host key has been confirmed, it is stored in WPS Workbench, and subsequent attempts toconnect to the same host machine will not require this to be reconfirmed.

6. If you elected to open the connection immediately, you will now be prompted for a password toauthenticate yourself on the host machine. Assuming that your system administrator has providedyou with the required password, enter it in the Password Required dialog and click OK.

There will now be an entry in the Link Explorer for your new connection. You will now need to add oneor more WPS server definitions to this connection in order to use WPS (refer to Defining a new WPSserver).

Remote host connection propertiesConnection properties are accessed by selecting the required connection in the Link Explorer, and thenright-clicking and selecting Properties from the context menu. The properties that can be selected viathe left of the Properties dialog are as follows:

Remote Connection OptionsThis 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 orIP address of the remote server, the SSH port (defaults to 22 if not specified), and the username you wish to connect to it with.


164

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

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

• The Use SSH Port Forwarding check box controls whether or not the SSH connection usesSSH port forwarding to send standard in and out information between the remote connectionand the 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 have 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 box and the Workbench will allowyou to save the settings. Otherwise, an error will be displayed and you will be required tospecify a host that does cuurrently exist.

Directory ShortcutsA directory shortcut is a shortcut to a directory on the remote file system. Default shortcuts aredefined for Home (~/) and Root (/) (that it to say, the file system root directory).To set up a new shortcut, click Add to display the following dialog:

After Directory Name, enter the shortcut name you want to use, and, after Directory Path, thefull path (as shown when you hover over the location in the File Explorer), and click OK. Theshortcut name then appears in the host file system in File Explorer when the host connection isopen. You can double-click a shortcut to change its definition. Other directory shortcuts can beedited as required, and removed from this property page.

Advanced connection optionsThere are circumstances where it is necessary to control the list of environment variables that theremote server will inherit when it is started. By default the server process will just inherit the defaultinteractive shell environment for the user under whose ID the server is being started. An example wouldbe the environment variables required in order to use a database library engine. On Linux, for example,this might require that the database client shared libraries be added to the LD_LIBRARY_PATH sothat they can be loaded by the WPS software. One way to do this is to modify the /etc/profileor ~/.profile file in order to add the required directories to the LD_LIBRARY_PATH. However this


165

may not always be desirable. An alternative on UNIX/Linux is to place a wpsenv.sh file in the WPSinstallation directory, or in your home directory. Its contents will be automatically run before the server islaunched. The output from any commands that you execute in this way can be seen in the Consoleview (refer to Console (for remote server standard output)).

On Windows, if you want the WPS server to acquire any special environment variables, you willneed to configure them in the normal way - by using the Control Panel to set them either as systemenvironment variables or specific to the relevant user.

Caution:All processes running as that user will see those variables, and there is no way to specify that theyshould only be visible to the WPS process.

Defining a new WPS serverWPS Workbench allows you to have multiple WPS servers defined on a particular host connection.

Proceed as follows to define a new server:

1. Having ensured that your connection to the host is open, launch the New WPS Server wizard bydoing one of the following:

• Ensure that you have the Link Explorer open ( Window ➤ Show View ➤ Link Explorer)open, right-click on the host connection to which you wish to add a server, and click on the

New WPS Server option in the context menu.

• From the main menu, select WPS ➤ Link ➤ New WPS Server ➤ Local (or substitute the name ofyour remote WPS server in place of Local ).

2. In the resulting New WPS Server dialog, enter the Server name (this must be unique across allconnections).

Note:If you are defining a New Remote WPS Server, there will be a field called Base WPS installdirectory, and in here you need specify the location of the WPS installation on the remote host, forexample:


166

3. In the last two check boxes, ensure that Start the server now is ticked if the server is to be startedimmediately, and that Start the server automatically on connection startup is ticked if the serveris to be started each time the connection is opened.

4. Click Finish to complete the wizard and create the new server definition.

There will now be entries in the Link Explorer, WPS Server Explorer, Output Explorer and ResultsExplorer for your new WPS server definition. Follow the steps in Local WPS server properties orRemote WPS server properties as appropriate, to configure startup options for the server.

Exporting host connection definitions to a fileTo simplify sharing host connection definitions within a work group, or to enable you to copy connectiondefinitions between workspaces, you can export connection definitions to a file, as follows:

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

2. Select the connections that you wish to export from the list in the Link Explorer view.3. From the right-click menu, select Export Host Connection.

4. Using the resultant Export to File dialog, enter the name of the file that you wish to create. This filewill contain the exported connection definitions in XML form, and have the extension .cdx.

The host connection definitions will be saved to the selected file. This file can then be distributedwithin your work group, or imported directly into another workspace on your machine. To import theconnection definitions into a workspace, refer to Importing host connection definitions from a file.


167

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. Launch the Import Host Connection dialog by doing one of the following:

• Ensure that you have the Link Explorer open ( Window ➤ Show View ➤ Link Explorer)open, and click Import Host Connection Definition.

• From the main menu, select WPS ➤ Link ➤ Import Remote Host Connection.

2. Using the Import Host Connection dialog, select the connection definition file (denoted by the suffix.cdx) containing the previously exported connection definitions.

Tip:Connections can also be imported by dragging a .cdx file onto the Link Explorer view.

The host connection definitions are imported from the selected file. If there are any name clashes, theimported connection definition is automatically renamed so that it has a unique name within your list ofconnections.

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, as follows:

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

2. Select the servers that you wish to export from the list in the Link Explorer.3. From the right-click menu, select Export WPS Server Definition....4. Using the resultant Export to File dialog, enter the name of the file that you wish to create. This file

will contain the exported server definitions in XML form, and have the extension .sdx.

The WPS server definitions will be saved to the selected file. This file can then be distributed withinyour work group, or imported directly into another workspace on your machine. To import the serverdefinitions into a workspace, refer to Importing WPS server definitions from a file.

Importing WPS server definitions from a fileThis task assumes that you have:

• Previously exported some WPS server definitions to a file, or else have been provided with anexport file created by someone else in your work group; And


168

• You have at least one host connection already configured, as a WPS server is associated witha host connection. (This will already be the case if you are creating a local server, as a localconnection is provided for you, but may not be the case if you are creating a remote server, forwhich a new connection needs to have been created in accordance with Creating a new remote hostconnection).

1. Launch the Import from File dialog by doing one of the following:

• Ensure that you have the Link Explorer open ( Window ➤ Show View ➤ Link Explorer)open, select a Host Connection, and then select Import WPS Server Definition from theright-click menu.

• From the main menu, select WPS ➤ Link ➤ Import WPS Server ➤ Host Connection Name

2. Using the Import from File dialog, select the server definition file (denoted by the suffix .sdx)containing the previously exported server definitions.

Tip:Servers can also be imported by dragging a .sdx file onto a host connection node in the LinkExplorer view.

3. Alternatively, servers can be imported by dragging WPS Server Definition Files (*.sdx) onto a HostConnection node in the Link Explorer view.

The WPS server definitions are imported from the selected file. If there are any name clashes, theimported server definition is automatically renamed so that it has a unique name within your list of WPSservers.


169

Database connectivityThis section gives a brief introduction to the setup of connectivity under Windows to common types ofexternal database to facilitate management of your Workbench data.

Note:For details of the WPS library engines for the different types of database, consult the WPS ReferenceFor Language Elements guide.

IntroductionWPS Workbench can be used in conjunction with the following database management systems, eitherthrough ODBC (Open Database Connectivity) or the associated native clients:

• Oracle, through the Oracle Instant Client - refer to Connecting to an Oracle database.• DB2, through the IBM Data Server Runtime Client - refer to Connecting to a DB2 database.• SQL Server, through the SQL Server Native Client - refer to Connecting to a SQL Server database.• MySQL through the MySQL Connector/C - refer to Connecting to a MySQL database.

Note:Wherever possible, you should use the native RDBMS client, rather than an ODBC client, to obtainthe best support for database options and the SAS language. Where this is not possible, refer toConnecting to a database using ODBC.

Supported client driversThe following client connector versions are supported:

Engine Windows client

Oracle Instant Client 11

DB2 IBM Data Server Runtime Client 10.5

SQL Server Microsoft SQL Server 2008 Native Client

MySQL Connector/C 6.0


170

Connecting to an Oracle databaseGetting data from an Oracle database when connecting from WPS running on a Windows platform.

Before installing the Oracle client software, ensure that:

• You have installed and licensed WPS.• You have the requisite administrator privileges to install both WPS and the Oracle client.

Note:When installing the Oracle client:

• You must match the WPS Workbench installation type - that is to say, the Windows (32-bit) client isrequired for the 32-bit version of WPS Workbench, and the Windows (x64) client is required for the64-bit version of WPS Workbench.

• You should download the version of the client that matches the version of the Oracle database towhich you are connecting.

The connector must be installed on the PC or server on which your SAS language programs will be run.Proceed as follows:

1. Download the basic Oracle Instant Client from the Instant Client download page of the Oraclewebsite.

2. Once the appropriate installation (.zip) file has been downloaded, create a folder for the instant clienton your PC, for example C:\oracle, and unzip the content of the file into that folder:

3. Add the Oracle Instant Client installation directory to the system Path variable, as follows:

a. In the Control Panel, select System ➤ Advanced System Settings.

b. Select Environment Variables, followed by Edit..., and add the path to the existing Path systemvariable.

4. Start WPS Workbench to ensure that the Path environment changes to the path are available.

You can view the Path variable in WPS Workbench using the following SAS language program:

DATA _null_;

LENGTH pathname $ 32760;pathname = SYSGET('PATH');PUT pathname= ;RUN;

The log output should contain the Oracle Instant Client installation directory added in the previousstep.

http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html


171

Once the client has been installed, test the database connectivity by using the following in WPSWorkbench:

LIBNAME DATASRC ORACLE user=<user_name> password=<password> path='<remote-id>/TNS';PROC DATASETS library=DATASRC;run;

Replace <user_name> and <password> with your user name and password for the server. The pathoption contains the server name (specified above as <remote-id>), and, optionally, a TNS name. ThePROC DATASETS command returns the names of all tables in the selected database; for databaseswith large numbers of tables, this program may take some time to run.

Note:For full details of PROC DATASETS, consult the WPS Reference For Language Elements guide.

Connecting to a DB2 databaseBefore installing the IBM Data Server Runtime Client, ensure that;

• You have installed and licensed WPS.• You have the requisite administrator privileges to install both WPS and the IBM Data Server

Runtime Client.

Note:When selecting the runtime client, you must match the WPS Workbench installation type - that is to say,the Windows 32-bit AMD and Intel x86 client is required for the 32-bit version of WPS Workbench, andthe Windows AMD64 and Intel EM64T client is required for the 64-bit version of WPS Workbench.

Proceed as follows:

1. Download the IBM Data Server Runtime Client from the Download Clients and Drivers page of theIBM website.

2. Once downloaded, locate and run the executable installation file. Follow the instructions in thewizard for the Typical installation type.

Note:For ease of future use, you are advised to ensure that the installation folder is on the system path.

3. Set the DB2CMDEXE environment variable to point to the db2cmd.exe file (typically C:\ProgramFiles\IBM\SQLLIB\BIN\db2cmd.exe), as follows:


b. Select Environment Variables, followed by New....c. Create a system variable with a Variable name of DB2CMDEXE, and a Variable value of

the DB2 client installation directory, for example C:\Program Files\IBM\SQLLIB\BIN\db2cmd.exe

http://www-01.ibm.com/support/docview.wss?uid=swg21385217


172

4. Following installation, you need to configure the connection from the client to the server you willaccess:

a. Open a command prompt and run DB2CMD. In the new window, type DB2 to access the commandline processor for the DB2 client.

b. Create a node to reference the remote database, using the following command:

catalog TCPIP node <node_name> REMOTE <server> SERVER <port_service>

<node_name> is the local connection name, <server> is the IP address or name of the serverhosting the database, and <port_service> is either the server port number or the databaseinstance name on the server.

c. Create a database instance reference (that you will connect to through the <node_name>created in the previous step), using the following command:

catalog database <database_name> AS <alias_name> AT NODE <node_name>

<database_name> is the instance of the database on the DB2 server, <alias_name> is the nameyou will use in the DB2 client to connect to the database instance, and <node_name> is thepreviously created connection name.

d. Connect to the previously created local connection name (<node_name>) using the followingcommand:

connect to <node_name> user <user_name> using <password>

<node_name> is the previously created connection name, and <user_name> and <password>are your user ID and password for the DB2 server.

If the connection is successful, the database connection information will be displayed and youcan close the command line processor for the DB2 client:

db2=> connect to testdb2 user Test using password

Database Connection Information Database server = DB2/LINUX SQL authorization ID = TEST Local database alias = TESTDB2

Once the client has been installed, start WPS Workbench and test the database connectivity by usingthe following in WPS Workbench:

LIBNAME DATASRC DB2 user=<user_name> password=<password> DSN=TESTDB2;PROC DATASETS library=DATASRC;run;

Replace <user_name> and <password> with your user name and password for the server.

Connecting to a SQL Server databaseBefore installing the Microsoft SQL Server 2008 Native Client, ensure that:


173

• You have installed and licensed WPS.• You have the requisite administrator privileges to install both WPS and the SQL Server Client.

Note:When installing the SQL Server client, you must match the WPS Workbench installation type - that is tosay, the X86 client is required for the 32-bit version of WPS Workbench, and the X64 client is requiredfor the 64-bit version of WPS Workbench.

Proceed as follows:

1. Download the Microsoft SQL Server 2008 Native Client (sqlncli.msi) installer from the MicrosoftSQL Server 2008 R2 Service Pack 3 Feature Pack page of the Microsoft website (click Downloadand then select sqlncli.msi).

2. Once the file has been downloaded, execute the file and follow the onscreen instructions to installthe client.

Start WPS Workbench, and test the database connectivity by using the following in WPS Workbench:

LIBNAME DATASRC SQLServr user=<user_name> password=<password> server=<remote-id>;PROC DATASETS library=DATASRC;run;

Replace <user_name> and <password> with your user name and password for the <remote-id>server.

Connecting to a MySQL databaseBefore installing the MySQL client software, ensure that:

• You have installed and licensed WPS.• You have the requisite administrator privileges to install both WPS and the MySQL client.

Note:When installing the MySQL client, you must match the WPS Workbench installation type - that is tosay, the Windows (32-bit) client is required for the 32-bit version of WPS Workbench, and the Windows(x64) client is required for the 64-bit version of WPS Workbench. The library names for the differentversions of the client are identical, so you can only have one version of the client (either 32-bit or 64-bit)registered on the Path system variable.

Proceed as follows:

1. Download the MySQL Connector/C installer (.msi) from the Download Connector/C page of theMySQL website.

2. Once the installation (.msi) file has been downloaded:

a. Double-click the downloaded file to begin installation (you will need to read and accept theMySQL licence agreement).

https://www.microsoft.com/en-us/download/details.aspx?id=44272

https://www.microsoft.com/en-us/download/details.aspx?id=44272

http://dev.mysql.com/downloads/connector/c/


174

b. Select a Typical installation, and click Install.3. Add the MySQL Connector/C installation directory containing libmysql.dll to the system Path

variable, as follows:


b. Select Environment Variables, followed by Edit..., and add the directory path to the existingPath system variable

4. Start WPS Workbench to ensure that the Path environment changes are available.

You can view the PATH variable in WPS Workbench using the following SAS language program:

DATA _null_; LENGTH pathname $ 32760; pathname = SYSGET('PATH'); PUT pathname= ;RUN;

The log output should contain the MySQL Connector/C installation directory added in the previousstep.

Once the connector has been installed, test the database connectivity by using the following in WPSWorkbench:

LIBNAME DATASRC MYSQL user=<user-name> password=<password> server=<remote-id> database=<dbase>;PROC DATASETS library=DATASRC;run;

Replace <user-name> and <password> with your user name and password for the <remote-id>server.

Remember:You must supply a database name <dbase> for the LIBNAME statement in order to connectsuccessfully.

Connecting to a database using ODBCODBC (Open Database Connectivity) is a database-independent connection option for WPS. Youshould use ODBC as the connection option where no native connection client exists.

ODBC provides the facility to create a SAS language program that stores data in one RDBMS, and thento modify the database storing the data without the need to modify your program significantly.


175

Caution:Using ODBC may limit the funtionality that would otherwise be available through a native client, forexample when using Explicit passthrough commands in PROC SQL. (Explicit passthrough uses SQLas understood by the server to which you are connecting, and passes those statements to the RDBMSverbatim.)

Each ODBC driver requires the creation of a DSN (Data Source Name), and the information requiredwhen creating this will vary between databases. The following procedure will create a DSN using theSQLite ODBC driver for use.

Note:The version of ODBC driver you select must match the WPS installation type - that is to say, if you havethe 32-bit version of WPS installed, select a 32-bit ODBC driver; and if you have the 64-bit version ofWPS installed, select a 64-bit ODBC driver.

1. Download the ODBC driver for SQLite from the SQLite ODBC Driver website.2. Once downloaded, double-click the executable file and follow the on-screen instructions to install the

driver.3. Create an empty file on your PC to hold the database, for example E:\data\mydata.sqlite.4. Create a DSN for the ODBC driver, as follows.

a. In the Control Panel, select Administrative tools and then choose either ODBC Data Sources(32-bit) or ODBC Data Sources (64-bit) as appropriate.

b. On the User DSN tab, click Add... and select SQLite3 ODBC Driver in the Create New DataSource dialog box.

c. In the SQLite3 ODBC DSN Configuration dialog box enter the following information:

• Data Source Name - The name to be referenced by the SAS language programs run in WPS,for example SQLITE.

• Database Name - The file name for the database, for example E:\data\mydata.sqlite.

Other information is optional, but may provide better data management within the database. Forexample, to enforce foreign key constraints, select Foreign Keys in the configuration window.Further details on the options can be found in the SQLiteODBC documentation.

d. Once all required options have been selected, click OK to create the DSN, and close the ODBCData Sources dialog box.

Once the DSN has been created, test the database connectivity by using the following in WPSWorkbench:

PROC SQL; CONNECT TO ODBC (DATASRC=<dsn-name>); EXECUTE (CREATE TABLE test (ID INTEGER, name TEXT)) BY ODBC; DISCONNECT FROM ODBC;QUIT;

Replace <dsn-name> with the Data Source Name entered in the DSN configuration dialog box.

http://www.ch-werner.de/sqliteodbc/


176

If the creation was successful, the Workbench log should contain the following information:

CONNECT TO ODBC (DATASRC=SQLITE);NOTE: Successfully connected to database ODBC as alias ODBC.EXECUTE (CREATE TABLE test (ID INTEGER, name TEXT)) BY ODBC;The statement completed successfully.NOTE: Successfully passed statement to database ODBC.


177

Configuration filesConfiguration files are files inrcorporating system options that control the initial WPS environment.Configuration files are used during WPS initialisation when WPS is run from the command line, andalso when the Workbench is being used.

You can open a configuration file as a basic text file in order to add, remove or change system optionsto 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.

Note: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 WindowsWhen 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 viathe -config option 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.

Caution:Overriding the default configuration file processing, specifically the loading of the wps.cfg file inthe WPS installation directory, must be done with care. There are many required options in the basewps.cfg file. If you choose to use the -config option, it is recommended that you either takea copy of the base wps.cfg file and modify it to suit, or that you make sure to include the basewps.cfg file in your customer configuration file and then override any settings that you need, forexample:

-set wpshome 'somewhere'-config !wpshome/wps.cfg/* And now set any options you want */

3. WPS then checks for a number of default configuration files, processing them in the following order:

a. wps.cfg in the WPS installation directory


178

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

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 platformsWhen 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 filesnamed 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 isloaded. 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


179

• 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 were specified on the command line.

6. WPS checks for the environment variable WPS_V3OPTIONS and processes it in the same way.7. Any options specified on the command line are then processed.

There are also so-called "restricted" configuration files that will always be processed. Any optionsin these files cannot be changed by any other method. The files are based on the user's useridand groupid. For example, if the user is <user> and the group is <group>, then the followingconfiguration files will be processed:

• misc/rstropts/rwps.cfg in the WPS installation directory• misc/rstropts/groups/<group>_rwps.cfg in the WPS installation directory• misc/rstropts/users/<user>_rwps.cfg in the WPS installation directory

Getting information about the Startup ProcedureIt is possible to check which configuration files have been processed by checking the CONFIG systemoption. 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.

1. Ensure that you have the WPS Server Explorer open.2. Right click on the relevant WPS server icon and select Properties from the context menu.

3. In the Properties dialog, select System Options from the list of available pages on the left handside, to display the values of all system options for the server.

4. Scroll down to CONFIG and higlight it to display all the configuration files that were 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 then generate information in the normal log outputindicating which configuration files were processed and which system options were set.

To set the VERBOSE option in the Workbench, change the Startup Options as follows:

1. Ensure that you have the WPS Server Explorer open.2. Right click on the relevant WPS server icon and select Properties from the context menu.

3. In the left hand menu of the Properties dialog, select Startup ➤ System Options.

4. On the right of the window, click Add... to display the Startup Option dialog.


180

5. Click Select... on the right of dialog to see a list of available options in a Select Startup Optionwindow.

6. Search for and/or scroll down to the VERBOSE option, and then double-click on it. The StartupOption dialog will then display your choice.

7. Click on the dropdown box next to Value and change the value to VERBOSE (or NOVERBOSE to turnthe option off).

8. Click OK.9. Click OK on the Properties dialog and you will be prompted to restart the server to apply your

changes.10.Check the log (see Viewing the log). The change to the VERBOSE option means that the processed

configuration files and the system options will be shown there when the Workbench restarts.


181

AutoExec fileAn AutoExec file is a program that is automatically executed when WPS is started. It can be used fora number of purposes, such as setting up common LIBNAMES so that they do not need to be added toevery program that is run.

Note:The LIBNAME statement is used when you want datasets to be stored in, and retrieved from, a directoryother than the default Work library (refer to Libraries). For full details of the LIBNAME languageelement, consult the WPS Reference For Language Elements guide.

When using WPS Workbench, the relevant AutoExec file will be executed when WPS is first launchedand, thereafter, each time that the WPS server is restarted.

The Workbench also allows code to be executed automatically before and/or after each program. SeeWPS Code Injection for more details.

WindowsWPS automatically looks for a file called autoexec.sas in the following hierarchy of directories:

1. (current directory)

2. My Documents

3. paths specified in the PATH environment variable4. the root directory of the current drive e.g. C:\5. the directory where WPS is installed.

Other operating systemsWPS automatically looks for a file called autoexec.sas in the following hierarchy of directories:

1. (current directory)

2. $HOME

3. the directory where WPS is installed.

Specifying a different fileIf you wish to run a different file automatically, or a file in a directory that is not in the hierarchy relevantto your operating system, then this can be achieved by setting the AUTOEXEC system option via theConfiguration files.

You can also do this using the WPS server properties, as follows:


182

1. In the WPS Server Explorer, Link Explorer, Output Explorer or Results Explorer,ensure that the server is running.



window.6. Search for and/or scroll down to the AUTOEXEC option, and then double-click on it. The Startup

Option dialog then displays your selection.7. Enter the the path to the configuration file that you wish to be used, into the Value text box, and then

click OK.8. Click OK on the Properties dialog and you will be prompted to restart the server and execute the file

that you have specified.


183

WPS Tips and Tricks

WPS Setup• You can use the WPS Link facility to set up and manage a remote client/server solution. Refer

to WPS Link client/server setup. For server authentication, refer to the WPS Link user guide andreference.

• If you are using WPS Link to execute programs on a Remote host only, and do not need theWPS Local Server, you can remove or disable it, in accordance with Configuring the local WPSinstallation.

• You can change the Workbench font. Refer to General Preferences.• You can change the background appearance of the Editor. Refer to Text Editor Preferences.• You can create keyboard shortcuts by changing the Eclipse key bindings under

Window ➤ Preferences ➤ General ➤ Keys. Refer to Shortcut Key Preferences.

Tip:To export and import your keyboard shortcuts between workspaces. Simply export your preferencesto an .epf file (refer to Backing up your Preferences), ensuring that you tick Keys Preferences.Then, when you start WPS in another workspace, import the preferences from that file usingFile ➤ Import… ➤ General ➤ Preferences, once more ensuring that you tick KeysPreferences.

• You can control the system options that are used in the WPS environment via Configuration files.Any modifications must be performed with care as they may impact other WPS users.

• You can set up common LIBNAMES, so that they do not need to be added to every program thatis run, via the AutoExec file. This file is executed when WPS is first launched and, thereafter, eachtime that the WPS server is restarted.

File Management• To display or create a different group of projects, you can switch to a different workspace. Refer to

Switching to a different workspace.• If you accidentally delete a file while using the Project Explorer, it is possible to restore the required

version of the file via the Workbench's Local history. Refer to Restoring from local history.• You can use the Project Explorer to compare different files and merge them with one another. Refer

to Comparing and merging multiple files.


184

• To access your files quickly on the hosts's file system, you can create directory shortcuts for usewith the File Explorer. If you are creating a remote host connection (refer to Creating a new remotehost connection), then you will automatically be prompted to create directory shortcuts. Otherwise,you can add them via the host connection properties in the Link Explorer - refer to Local hostconnection properties (Directory Shortcuts) or Remote host connection properties, as appropriate.

SAS programs• To help you get started, there are some programs supplied in a sample project that you can import

into WPS Workbench. Refer to Importing the sample and other projects.• You can specify code that is to be executed automatically before and/or after each program (refer to

WPS Code Injection).• You can create templates containing code snippets that can be re-used. Refer to Entering WPS

code via templates.

Tip:To export and import your preferences (including templates) between workspaces so that you donot need to repeat your setup each time, simply export your preferences to an .epf file (refer toBacking up your Preferences), ensuring that you tick WPS Preferences. Then, when you startWPS in another workspace, import the preferences from that file using File ➤ Import… ➤ General ➤ Preferences, once more ensuring that you tick WPS Preferences.

Running SAS Programs• To help with your testing, you can run just part of a program from the Workbench. Refer to Running

part of a program.• You can run multiple programs simulaneously on the same machine by distributing jobs over more

than one server. You can define multiple servers on a single host, regardless of whether that host isLocal or Remote (refer to Defining a new WPS server).

Note:Although you can only have one Local host, the only restriction on the number of local servers thatcan be created on that host is the local machine resources. Howerver, in order to set up multipleRemote hosts, you require sufficient WPS licence keys to cover the setup of each one. To set up anew host, refer to Creating a new remote host connection.

• You can run WPS in Command Line mode. Refer to Running a program from the command line ofa Windows platform or Running a program from the command line of a non-Windows platform, asappropriate.

• You can access databases from your SAS programs. Refer to Database connectivity.

Program output and results• You can control whether or not the ODS destinations (HTML and Text (LISTING)) are to be

controlled automatically, and, if so, which specific types of output are to be used. Refer to ResultOptions Preferences.


185

• Although your WORK location is temporary in that it is automatically cleared of all data when yourWPS session ends (refer to Libraries), you can set up a permanent location in accordance with SetWORK location.

• You can remove the results of program output either selectively (refer to Clearing the results output)or non-selectively (refer to Restarting the server). If you restart the server, you should be aware thatyou will lose your temporary work, meaning that programs will no longer be able to interact with anyobjects created prior to the restart.

Datasets• You can edit datasets from within the Workbench (version 3.2 onwards), using in-place context-

aware editing and column re-ordering. Refer to Editing a dataset.• You can export datasets as delimited and fixed width text, and also as Microsoft Excel

spreadsheets. Refer to Exporting datasets.


186

TroubleshootingThe following is a list of potential problems and how to resolve them:

Why are the icons greyed out so that I cannot run any programs?

The icons will be greyed out if any of the following are true:

• The server on which you are running programs is not successfully licensed (refer to Applyinga licence key), or has been uninstalled (refer to Configuring the local WPS installation).

• The name of the program file open in the Editor does not end in .sas or .wps.• The focus of the mouse is in a view other than the Editor.

Why do I see a dialog saying that there is no default server on which to submit the program?

It is usually because you have clicked the button to run a program and the default WPSserver has been removed. If you have other WPS servers defined, you can select one of those asthe new default (refer to Default WPS server). Alternatively, you can restore the WPS server thatwas removed (refer to Defining a new WPS server) and reset it as the default.

Why are the characters in my files not being displayed correctly?

This is likely to be an encoding issue. You should follow all the steps in WPS server LOCALE andENCODING settings and General text file encoding, and then restart the Workbench. If you haveimported the files that are displayed incorrectly, then you many need to re-import them.

Why can't I start the Workbench?

If the Workbench usually starts without any problems, but then suddenly fails to start up, it maywell be that you have run out of disk space, causing one or more files in the Eclipse .metadatadirectory for your current workspace to become corrupted (the .metadata directory holdscached information, Local history, saved dialog box positions, and so on). Pointing to a differentworkspace (refer to the Workspace Launcher), can help to verify that there is something wrongwith the .metadata directory in the current workspace. The simplest solution is to rename the.metadata folder in the corrupt workspace directory to something else, restart WPS, and thenpoint to the workspace again. WPS should start, but there will be an empty list of projects in theProject Explorer. Do not worry - your projects and source code have stayed exactly where theyused to be, and you simply need to regenerate the metadata by importing the existing projects(refer to Importing the sample and other projects). To display .metadata files that may behidden, refer to WPS File Explorer Preferences (Hidden Files).

How do I get the Workspace Launcher back?

If you are not prompted to select a workspace when you start the Workbench, then this generallymeans that you have previously ticked the Use this as the default and do not ask again box inthe Workspace Launcher dialog. To resolve this, tick the Prompt for workspace on startup boxin Window ➤ Preferences ➤ General ➤ Startup and Shutdown ➤ Workspaces, and then restartWPS.


187

How do I increase my Java heap storage in the event of Java Runtime errors?

Refer to Show Heap Status.


188

Making technical supportrequestsHow you access technical support for your WPS software depends on how you purchased yoursoftware. If you made a standard purchase of WPS software you will have an annual subscriptionlicence that entitles you to unlimited free upgrades throughout the twelve months, and free emailsupport via [email protected]. We always respond promptly to requests for emailsupport and will do our best to work within an acceptable timescale.

Larger customers may have additional support arrangements in place. In this case, we may oftenprovide access to our online Issue Tracking System. The handling of technical support requests may becarried out via one or more super users that have been nominated by your organisation - so you needto be aware who these people are.

Resolutions to problems may include suggested workarounds or may require you to update your WPSsoftware installation.

Note:Due to the complex nature of the SAS language, it may require some extended interaction betweenWorld Programming and yourselves to identify and resolve the causes of the problems.

WPS server log filesFor certain types of issue, you may be requested to provide the .log files. These are stored undera directory called .metadata that is found in the workspace that is currently being used by theWorkbench. In Windows, this current workspace is My Documents\Wps Workspaces\Workspacen;and, under a non-Windows platform, it is /home/<username>/WPS Workspaces/Workspacen;where n is the number of the workspace.

Note:Because .metadata and .log start with a period, they will normally be hidden and you will need toensure you can see these types of file. If using a graphical interface, then edit your Folder Options toshow hidden files and folders. On a command line, having changed directory to .metadata, use thecommand ls -la or ls -a to list every file in the directory, whether hidden or not.

mailto:[email protected]


189

Legal NoticesCopyright © 2002-2018 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.

TrademarksWPS 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 NoticesWorld Programming Limited is not associated in any way with the SAS Institute.

WPS is not the SAS System.

The phrases "SAS", "SAS language", and "language of SAS" used in this document are used to refer tothe computer programming language often referred to in any of these ways.

The phrases "program", "SAS program", and "SAS language program" used in this document are usedto refer to programs written in the SAS language. These may also be referred to as "scripts", "SASscripts", or "SAS language scripts".

The phrases "IML", "IML language", "IML syntax", "Interactive Matrix Language", and "language of IML"used in this document are used to refer to the computer programming language often referred to in anyof these ways.

WPS includes software developed by third parties. More information can be found in the THANKS oracknowledgments.txt file included in the WPS installation.