QuickSTAF

By Testformation, Inc.

GUI client for STAF V3

User's Guide

User's guide rv:1.39 for QuickSTAF 1.0 rv:1.8

June 2011

The software described in this book is furnished under a license agreement and may be used only in accordance with the terms of the agreement.

No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of Testformation, Inc..

Feedback

Please direct any comments or suggestions about this document to: quickstaf@testformation.com.

Technical Support

For technical support, log on to QuickSTAF Support website.


Table of Contents

1. Product overview
Introducing QuickSTAF
2. Getting started
Determining system requirements
Installing QuickSTAF
Getting help
Starting QuickSTAF
Parts of the main window
Brief tutorial
Closing QuickSTAF
Uninstalling QuickSTAF
3. Setting up QuickSTAF
Pool
Adding a pool
Editing a pool
Changing the position of a pool
Deleting a pool
Machine
Adding a machine
Adding machines and services as batch processing
Editing a machine
Changing the position of a machine
Deleting a machine
Service
Adding services
Updating services
Updating services as batch processing
Editing service help before adding or updating services
Deleting services
Fixing a service
Command
Resetting options
Preference
Choosing view preferences
Choosing edit preferences
4. Using QuickSTAF
Submitting a request
Saving a response
Changing response format
Printing a response
Viewing online service help
Stopping a long running request
Stop loading a response
Finding a machine
Choosing a pool
History
Enabling history
Viewing a history
Navigating history
Narrowing down a history
Deleting session history
Deleting history
Working with text
Selecting, cutting, copying, pasting and deleting text
Finding text
5. Maintaining QuickSTAF
Backing up application data
Restoring application data
Backing up history data
Restoring history data
A. Keyboard shortcuts
B. Common error messages
C. Setting environment variables
D. Technical background
E. Modifying service help
Editing service help
Meanings of syntax errors
Correcting service help errors when adding services
Correcting service help errors when updating services
F. Service help specification
Service help format
Service help to GUI element map
Determining textbox size
G. HTML table format specification
Glossary
Index

List of Figures

2.1. Statusbar info
E.1. A missing ']'
E.2. A missing '['
F.1. NAMEDCOUNTER service help
F.2. Parent and child options in a service help
F.3. Parent option not selected
F.4. Parent option selected
F.5. Recurring option in a service help
F.6. Recurring option after conversion
F.7. After specifying the first value
F.8. After creating the second block of elements
F.9. After specifying the second value
F.10. After removing the second block of elements
F.11. Event has multiple LIST command

List of Tables

A.1. General Shortcut keys
C.1. Supported environment variables
F.1. External services
F.2. DEMO service help conversion
F.3. Options-GUI elements mapping
F.4. EVENT REGISTER options
G.1. Simple list table
G.2. Simple map table
G.3. List of map table
G.4. Complex table

List of Examples

F.1. DEMO service help
G.1. Simple list
G.2. Simple map
G.3. List of map
G.4. Complex

Chapter 1. Product overview

Table of Contents

Introducing QuickSTAF

QuickSTAF is a multi-platform GUI client for Software Testing Automation Framework (STAF) V3. It is also known as STAF GUI.

STAF GUI is available for Windows, Linux and Mac OS X in two different editions.

  1. QuickSTAF Network sends requests to any machine on the network.

  2. QuickSTAF Standalone sends requests to only local machine.

Introducing QuickSTAF

STAF GUI automatically creates GUI elements from service help for any services. It displays machines, services and commands as hierarchical tree elements and options as other GUI elements (field, textbox, checkbox and drop-down list).

STAF GUI is able to display responses in HTML table format, as well as STAF default (text). You can search a word in response, as well as save or print the response in HTML or text format.

In STAF GUI, you can enable request history for later review. You can also backup and restore the application and history data.

Additional features

  1. Supports any STAF services including external custom services.

  2. Multiple submissions with progress timer display.

  3. Supports both IPv4 and IPv6 (if STAF supports).

  4. Online service help is available when composing a request string.

Chapter 2. Getting started

This section explains how to get, install and start using STAF GUI.

Determining system requirements

Any version of STAF V3.

  • Windows

    • Supported Operating Systems

      • Windows 2000

      • Windows XP

      • Windows Server 2003

      • Windows Vista

      • Windows 7

    • Minimum Hardware

      • Pentium 233 MHz (Recommended: Pentium 500 MHz or greater)

      • 64 MB RAM (Recommended: 128 MB RAM or greater)

      • 52 MB hard drive space

  • Linux

    • Software Requirements

      • GTK+ 2.10 or higher

      • GLib 2.12 or higher

      • Pango 1.14 or higher

      • X.Org 1.0 or higher

  • Mac OS X

    • Supported Operating Systems

      • Mac OS X 10.4 and later

    • Minimum Hardware

      • Macintosh computer with an Intel x86 or PowerPC G3, G4, or G5 processor

      • 128 MB RAM (Recommended: 256 MB RAM or greater)

      • 200 MB hard drive space

Installing QuickSTAF

Visit the QuickSTAF Download to get the installer for your operating system.

  • Windows

    Double-click on the downloaded STAF GUI installer.

    Note

    In Windows Vista and Windows 7, you may see a User Account Control message. Click the Allow button.

    In the Setup - QuickSTAF Network window, Click the Next button and follow the on-screen instructions.

  • Linux

    1. Open a Terminal and go to the directory where you have downloaded STAF GUI file.

    2. Extract the contents of the downloaded file:

      tar xjf quickstaf-network-1.0.en-US.linux-i686.tar.bz2

    3. Move the program directory to your installation directory:

      mv quickstaf <installation-directory>/

  • Mac OS X

    1. Double-click on the downloaded STAF GUI package.

    2. In the QuickSTAF window, drag the QuickSTAF icon to the Drag to here folder.

Getting help

This book, the STAF GUI User's Guide, assumes that you are familiar with your computer and basic functions, such as starting a program, opening and saving files.

This book is your first line of support for using STAF GUI. Online versions of this book are available in HTML and PDF formats. To display an online version of this book, choose either

  • HelpUser's GuideHTML Single Page,

  • HelpUser's GuideHTML Page By Chapter or

  • HelpUser's GuidePDF.

Free online support

Visit the QuickSTAF Support website to get support from other users who participate in the newsgroup, forum, or mailing list. However, there is no guarantee that your question will be answered since participation on these sites is entirely voluntary.

Paid support

Alternatively, you can pay for support services. Service contracts can be purchased from QuickSTAF Support website. This website provides more information about the paid support.

Starting QuickSTAF

  • Windows

    There are two ways to start STAF GUI:

    1. Choose StartAll ProgramsQuickSTAFQuickSTAF.

    2. In command prompt:

      1. cd <absolute path to STAF GUI installation directory>

      2. quickstaf

  • Linux

    1. cd <absolute path to STAF GUI installation directory>

    2. ./quickstaf

  • Mac OS X

    There are two ways to start STAF GUI:

    1. In the application window:

      1. Choose GoApplications (Command+Shift+A).

      2. In the Applications window, double-click on the QuickSTAF icon.

    2. In command prompt:

      1. cd /Applications/QuickSTAF.app/Contents/MacOS

      2. ./quickstaf

Parts of the main window

The main window contains the menubar, toolbar, pool tabs and tabbed sections, pool navigation buttons, and statusbar.

Menubar

  • The File menu contains tasks that are commonly associated with files, such as backup, restore, save, and print.

  • The Edit menu contains tasks that are associated with text editing, such as cut, copy, paste, delete, find, and select.

  • The Setup menu contains the tasks that add and update pools, machines and services.

  • The History menu contains tasks that are associated with history, such as navigating and enabling history. It also has a link to the History window where you can manage the history.

  • The Tools menu contains the find machine tool and preference settings.

  • The Help menu contains links to this user's guide and about dialog.

Toolbar

The toolbar contains frequently used tasks, such as navigating history, clearing session history and interrupting response load.

You are able to navigate the history, backword and forward, by using .

You can also view history by randomly accessing by using this drop-down button .

When history is not enabled, the requests that you have sent and the response you have received are stored in the session cache. The cache will be cleared by closing the application. But, you are able to clear this cache by using . This will clear all session history across the pool.

When a response is very large, it may take a longer to load into the Response pane. You can interrupt the loading by using .

Pool tab and tabbed section

In STAF, the machine provides services and the services provide functionalities through the command names. In STAF GUI, this hierarchy of information is represented as a tree in the Command pane. Since the pool has machines, the pool becomes the root of this hierarchy and is represented as a tab. The following icons are used to represent these hierarchical items.

Pool

Machine

Service

Service (to be fixed)

Command

The tabbed section for a pool contains the Command pane, the Option pane, the Submit drop-down combination box, the Submit button, and the Response pane.

In STAF GUI, you have to select a command in order to submit a request. Whenever you select a command, if there are any options, they are displayed in the Option pane. When you specify these options, STAF GUI composes the current request automatically and displays in the Submit drop-down combination box. If the command has any required options, then you have to specify them all in order to submit a request. Otherwise, the Submit button will be disabled. You submit a request by clicking on the Submit button.

Quotes are required around the values in the textboxes if they contain spaces.

The online service help is available in the Service Help tabbed section of the Response pane. You are able to view this when you select a command in the Command pane.

After submiting a request, you can view the response in the Response tabbed section of the Response pane.

Pool navigation buttons

You can select a pool using the Pool navigation buttons. These buttons will only display when a pool tab goes out of view. You can also use the List all pools button to select a pool randomly.

Statusbar

In STAF GUI, the statusbar always displays the current status of the request and response. The information that displays in the statusbar is listed in Figure 2.1, “Statusbar info”.

Figure 2.1. Statusbar info


Every request that you send will be displayed in the message area of the statusbar until a response comes. For a larger response, it may take a while to load into the Response pane. This will be displayed in the progressmeter area of the statusbar. Once the response has fully loaded, the statusbar will display its details.

The following statusbar sequence diagrams show the life-cycle of a request.

  1. A request has just been sent.

  2. The response is converting into an HTML table.

  3. The response is loading into the Response pane.

  4. The response has been received.

History

You can manage history in the History window. The History menu provides access to this window. In order to store the request and response as history, you must enable it.

The History window contains the Backup and Restore menu, the Command pane, and the History pane. The Backup and Restore menu provides the tasks that backup and restore the history data. The Command pane contains pool, machine, service, and command in a hierarchal tree form. The History pane lists the request and date in a table form. The list in the table is ordered by the date. However, you can't view responses in the History window.

You can narrow down history by pool, machine, service, or command by selecting the respective item in the Command pane. You can delete the history from the History pane by selecting the rows in the table and pressing the Delete key.

Brief tutorial

This section assumes that STAFProc is running and you have installed STAF GUI on your machine. Otherwise, see the STAF V3 User's Guide for instruction on starting STAFProc and the section called “Installing QuickSTAF” for instruction on installing STAF GUI.

In addition to the above assumption, it is also assumed that STAFProc is running with the default instance name, which is STAF. Otherwise, see the section called “Editing a pool” for instruction on setting STAF instance name.

In this tutorial you are going to use the STAF GUI to list the services on your local machine. Without STAF GUI, you achieve this by typing the following command at the command prompt and pressing the Enter key.

STAF LOCAL SERVICE LIST SERVICES

  1. Start STAF GUI. See the section called “Starting QuickSTAF” for instructions on starting STAF GUI. When you start STAF GUI, for the very first time, a pool named Default and a machine named LOCAL is added for you.

  2. Since the list all services functionality is provided by the Service service, you need to add the service on LOCAL machine. Right-click on the LOCAL machine.

  3. Choose Add Services.

  4. In the Services window, select the SERVICE row under the Name column.

  5. In the Services window, click the Add button.

  6. Now the SERVICE service is displayed under the LOCAL machine.

  7. Expand the SERVICE service.

  8. Select the LIST command.

  9. In the Option pane, select the SERVICES option from the drop-down list.

  10. Observe that the request was composed in the Submit drop-down combination box. Click the Submit button.

  11. Now, services are listed in the Response tabbed section. Scroll the response area to see the list of all the services.

In STAF GUI, this is how you send a request to any service in any machine.

Closing QuickSTAF

  • Windows and Linux:

    Choose FileExit QuickSTAF.

  • Mac OS X:

    QuickSTAFExit QuickSTAF (Command+Q).

Alternately, you can also click the close button on the STAF GUI main window.

Uninstalling QuickSTAF

To completely uninstall STAF GUI, you need to uninstall the application and remove the data directory.

  • Windows:

    1. Choose StartControl Panel.

    2. In the control panel, double-click the Programs and Features icon.

    3. In the Uninstall or change a program panel, double-click the QuickSTAF Network icon.

      Note

      In Windows Vista and Windows 7, you may see a User Account Control message. Click the Continue button.

    4. In the QuickSTAF Network Uninstall window, click the Yes button and follow the on screen instructions.

    5. In command prompt,

      • For Windows 2000 and XP,

        rmdir C:\Documents and Settings\<user name>\Application Data\Testformation\QuickSTAF

      • For Windows Server 2003, Vista and 7:

        rmdir C:\Users\<user name>\AppData\Roaming\Testformation\QuickSTAF

  • Linux:

    In command prompt,

    • rm -rf <STAF GUI installation directory>

    • rm -rf ~/.testformation/quickstaf

  • Mac OS X:

    In command prompt:

    1. rm -rf /Applications/QuickSTAF.app

    2. rm -rf ~/Library/Application Support/QuickSTAF

Chapter 3. Setting up QuickSTAF

In order to submit a request, STAF GUI needs to know the machines, services and commands. This section explains how to set the required information before you use STAF GUI.

In the STAF environment there are many machines connected in network. In that environment, machines can be grouped for various purposes. For example, some machines can be grouped for a department and some for a project and the others for a demographic region. When you work on many machines, it is easier if you partition these machines into some groups. STAF GUI provides pools for this purpose.

Besides partitioning the machines, pools also provides environment-variable settings. When you send a request to a machine in a pool, STAF GUI uses these environment variables to initiate the request.

You can create as many pools as you want, and you can add as many machines to a pool as you want. Pool names, however, can't be identical. Similarly, within a pool, machine names can't be identical.

Pool

Adding a pool

To display the add pool dialog, choose SetupAdd Pool (Ctrl+L).

In the Pool dialog:

  1. Enter a name in the Pool Name text box.

  2. In the Request tabbed section:

    • To specify a static handle number, select the Use static handle radio button and enter a handle number in the textbox beside it. Otherwise, a new handle will be created for each request.

    • To specify an instance name, enter a name in the STAF Instance Name textbox. Otherwise, leave the default value.

    In the Response tabbed section:

    • Select any of the response formats you like.

    • To specify table lines per record, select the STAF default radio button and select the STAF table lines per record check box and enter a number in the textbox beside it.

    • To specify indent delta, select the STAF verbose radio button and select the STAF indent delta check box and enter a number in the textbox beside it.

    • To specify STAF replace nulls, select the STAF replace nulls check box and enter a number in the textbox beside it.

    • To set STAF ignore indirect objects, select the STAF ignore indirect objects check box.

    • To set quiet mode, select the STAF quiet mode check box.

  3. To test your settings and add:

    • To test your environment-variable settings, click the Ping LOCAL button. This will send a PING request to the LOCAL machine using these environment variables.

    • To add and display the Machine dialog, click the Proceed to add machine button.

    • To add, click the Add button.

Editing a pool

There are two ways to display the edit pool dialog:

  1. Choose SetupEdit Pool (Ctrl+E).

  2. Select the pool tab.

    1. Right-click on the tab.

    2. Choose Edit Pool.

Note

You can't edit a pool if the pool has any pending requests.

See the section called “Adding a pool” for instructions. Editing on the Pool dialog is the same when either adding or editing a pool, except for the appearance of the following when editing:

  • An Update button will display in place of the Add button.

  • The Proceed to add machine button will be disabled.

Changing the position of a pool

To move a pool left or right by one position:

  1. Select the pool tab.

  2. Right-click on the tab.

  3. To move the pool left choose Move left, or to move the pool right choose Move right.

Deleting a pool

Since a pool contains machines, deleting a pool will delete the hierarchy. You may not delete a pool if the pool has any pending requests. To delete a pool:

  1. Select the pool tab.

  2. Right-click on the tab.

  3. Choose Delete Pool.

  4. In the Delete Pool dialog, click the OK button to delete. You may need to wait a while for the pool to be deleted.

If you do not want to display the Delete Pool confirmation dialog, select Do not ask next time before you click OK. If you want to display this dialog again, see the section called “Choosing edit preferences”.

Machine

Adding a machine

There are two ways to display the add machine dialog:

  1. To add a machine in the selected pool, choose SetupAdd Machine (Ctrl+M).

  2. Select the pool tab.

    1. Right-click on that tab.

    2. Choose Add Machine.

In the Machine dialog:

  1. Specify a name in the Machine name textboxes as follows:

    1. In the first textbox, enter the interface name. This value is optional.

    2. In the second textbox, enter the system identifier name.

    3. In the third textbox, enter the port number. This value is optional.

  2. Enter an alias name for this machine in the Display as textbox. This value is optional. If entered, this value will display in the Command pane.

  3. Test the machine name and add:

    • To test the machine name, click the Ping button. This will send a PING request to that machine.

    • To add and display the Services dialog, click the Proceed to add services button.

    • To add, click the Add button.

Adding machines and services as batch processing

You can add machines and all their services as a batch. In this non-interactive mode, if any error occurs in the process of adding a service, it will display the error in the Error log textbox and move ahead to the next one. Once you have started this batch process, you can't use the application until it is completed. Depending on the number of machines, it may take a while to complete. You can cancel this process at any time.

When it proceeds to the end, the progressmeter will display 100%. If you cancel, the dialog box will close. In either case the Machine names textbox and the Error log textbox retain their values.

To display the add machines and services dialog, choose SetupNon-interactiveAdd Machines and Services.

In the Machines and Services dialog:

  1. To add all services of all machines in the current pool, click the Dump all machines button. This will copy all the machines in the current pool to the Machine names textbox.

  2. Enter names in the Machine names textbox on separate lines.

  3. To add, click the Add button. To clear error logs, click the Clear logs button.

Editing a machine

To display the edit machine dialog,

  1. In the Command pane, right-click on that machine.

  2. Choose Edit Machine.

Note

You can't edit a machine if it has any pending requests.

In the Machine dialog:

  1. To move this machine into another pool, select a pool from the Pool name drop-down list.

  2. Specify a name in the Machine name textboxes as follows:

    1. In the first textbox, enter the interface name. This value is optional.

    2. In the second textbox, enter the system identifier name.

    3. In the third textbox, enter the port number. This value is optional.

  3. Enter an alias name for this machine in the Display as textbox. This value is optional. If entered, this value will display in the Command pane.

  4. To test the machine name and update:

    • To test the machine name, click the Ping button. This will send a PING request to that machine.

    • To update, click the Update button.

Changing the position of a machine

In the Command pane, drag the machine to the position.

Deleting a machine

Since a machine provides services, deleting a machine will delete the hierarchy. To delete a machine,

  1. In the Command pane, right-click on that machine.

  2. Choose Delete Machine.

  3. In the Delete Machine dialog, click the OK button to delete. You may need to wait a while for the machine to be deleted.

Note

You can't delete a machine if the machine has any pending requests.

If you do not want to display the Delete Machine confirmation dialog, select Do not ask next time before you click OK. If you want to display this dialog again, see the section called “Choosing edit preferences”.

Service

Adding services

To display the add services dialog,

  1. In the Command pane, right-click on a machine to which you want to add service.

  2. Choose Add Services.

In the Services dialog, all available services are listed in a table with a Name column header.

  1. In that table, select all the services that you want to add.

  2. To add services, click the Add button.

Note

You can edit service help before it adds commands and options. If you have enabled this, the Edit Service Help window will display. See the section called “Editing service help” for instructions.

Note

If a service has any syntax errors, the Correct Service Help Error dialog will display. See the section called “Correcting service help errors when adding services” for instruction.

Updating services

You can update a single service or all the services in a machine. However, you can update only those services that have been added. First the program checks for available updates. Depending on the number of services, it may take a while to find the updates.

Note

You can edit service help before it updates commands and options. See the section called “Editing service help before adding or updating services” for instructions on editing service help.

To display the update services dialog,

  • For a single service:

    1. In the Command pane, right-click on the service that you want to update.

    2. Choose Update Service.

  • For all the services:

    1. In the Command pane, right-click on a machine whose services you wish to update.

    2. Choose Update Services.

    Note

    You can't update services by right-clicking on a machine if the machine has any pending requests.

In the Services dialog, current services are listed in a table with a Name column header. Updatable services can be selected.

  1. In this table, select all the services that you want to update.

  2. To update services, click the Update button.

Note

If you have enabled the Edit service help before add or update feature, the Edit Service Help window will display. See the section called “Editing service help” for instructions.

Note

If a service has any syntax errors, the Correct Service Help Error dialog will display. See the section called “Correcting service help errors when updating services” for instructions on correcting service help.

Updating services as batch processing

You can update all the services in all the machines in a pool as a batch. In this non-interactive mode, if any error occurs in the process of updating a service, the error will be displayed in the Error log textbox and the process will move ahead to the next service. Once you have started this batch process, you can't use the application until it is completed. Depending on the number of services, it may take a while to complete. You can stop this process at any time.

When it is completed, the progressmeter will display 100%. If you cancel, the dialog box will close. In either case the Error log textbox retains its value.

To display the update services of all machines dialog, choose SetupNon-interactiveUpdate Services.

In the Machines and Services dialog, the Pool name field displays the current pool name and the Machine names read-only textbox displays all the machines in the current pool.

  • To update, click the Update button.

  • To clear error logs, click the Clear logs button.

Editing service help before adding or updating services

If you set this preference, when you add or update a service the next time, the Edit Service Help dialog will display. To display the Preference window, choose ToolsPreference (Ctrl+R).

In the Preference window, in the Service tabbed section,

  1. Select the Edit service help before add or update checkbox.

  2. Click the Close button.

Deleting services

You can delete a single service, some of the services, or all the services.

  • For a single service:

    1. In the Command pane, right-click on a service that you want to delete.

    2. Choose Delete Service.

      If you do not want to display Delete Service confirmation dialog, select Do not ask next time before you click OK. If you want to display this dialog again, see the section called “Choosing edit preferences”.

  • For many services:

    1. In the Command pane, right-click on a machine whose services you want to delete.

    2. Choose Delete Services.

    Note

    You can't delete services by right-click on a machine if the machine has any pending requests.

    In the Services dialog:

    All current services are listed in a table with a Name column header.

    1. In that table, select the services that you want to delete.

    2. To delete the services, click the Delete button.

      If you do not want to display Delete Service confirmation dialog, select Do not ask next time before you click OK. If you want to display this dialog again, see the section called “Choosing edit preferences”.

Fixing a service

When you add a service, if the service help has a syntax error that you might have opted to fix later. This section explains how to fix those services.

To fix a service,

  1. In the Command pane, right-click on a service that needs to be fixed ( ).

  2. Choose Fix Service Help Error.

See the section called “Updating services” for instructions. The procedure for fixing a service is the same as that for updating a service.

Command

Resetting options

Resetting options will reset the GUI elements in the Option pane back to the default states. To reset options,

  1. In the Command pane, right-click on the command whose options need to be reset.

  2. Choose Reset options.

Note

Resetting the Option pane will also clear the current value in the Submit drop-down combination box and Response pane.

Preference

Choosing view preferences

You can view important values on or hide them from the statusbar by changing settings in preference. To display the Preference dialog, choose ToolsPreference (Ctrl+R).

  1. In the Preference window, in the View tabbed section, select or unselect all that apply.

  2. Click Close button.

Choosing edit preferences

You can enable or disable confirmation dialogs in preference when you delete a pool, machine or service. To display the Preference dialog, choose ToolsPreference (Ctrl+R).

  1. In the Preference window, in the Edit tabbed section, select or unselect all that apply.

  2. Click Close button.

Chapter 4. Using QuickSTAF

Submitting a request

To submit a request,

  1. In the Command pane, if necessary expand the machine and service that you want to send the request.

  2. In the Command pane select the command under the service. As a result of the selection,

    • Options display in the Option pane if the command supports them.

    • The machine, service and default request string display in the Submit drop-down combination box.

    • The Submit button is enabled only if the default request string satisfies the service help definition. Otherwise, it is disabled.

  3. To specify options, specify appropriate values in the Option pane if necessary. As a result of these changes,

    • The request string that displays in the Submit drop-down combination box changes accordingly.

    • The Submit button becomes enabled if the request string satisfies the service help. Otherwise, it is disabled.

  4. To submit the request, click the Submit button. As a result,

    • If the request takes more than one second to respond, in the Command pane, a row displays under the command with a progress icon, submit number and a timer which displays elapsed time. This row remains visible until the request responds. The pool tab icon also displays the progress icon until it responds.

    • The response will display in the Response tabbed section of the Response pane.

Tip

You can submit up to 516 requests at the same time.

Saving a response

To save a response, choose FileSave Response As (Ctrl+S).

In the Save As dialog,

  • Windows

    The default file name response displays in the File name drop-down combination box. The default file type HTML Files displays in the Save as type drop-down combination box.

    1. If necessary, specify a name in the File name drop-down combination box.

    2. If necessary, choose a file type in the Save as type drop-down combination box.

    3. To save, click the Save button.

  • Linux

    The default file name response displays in the Name textbox. The default file type HTML Files displays near the lower right corner.

    1. If necessary, specify a name in the Name textbox.

    2. If necessary, choose a file type which displays near the lower right corner.

    3. To save, click the Save button.

  • Mac OS X

    At the top of the dialog, the default file name response.html displays in the Save As textbox. At the bottom, the default file type HTML Files displays in the Save As drop-down list.

    1. If necessary, specify a name in the Save As textbox.

    2. If necessary, choose a file type in the Save As drop-down list.

    3. To save, click the Save button.

Tip

STAF GUI supports HTML and Text file types. When you save a response, follow these guidelines. If your response is in HTML table format, then choose HTML file type. Otherwise (STAF default, STAF verbose and STAF raw), choose the Text file type.

Changing response format

There are two ways to change response format:

  1. In the Response pane,

    1. Right-click on the Response tab.

    2. Choose a menu from the popup menu.

  2. See the section called “Editing a pool” for instruction on selecting a response format.

Printing a response

To print a response, choose FilePrint (Ctrl+P).

In the Print dialog,

  • Windows

    To print, click the OK button.

  • Linux

    To print, click the Print button.

  • Mac OS X

    To print, click the Print button.

Viewing online service help

Select a command in the Command pane. Service help displays in the Service Help tabbed section of the Response pane.

Stopping a long running request

To stop a request,

  1. In the Command pane, right-click on a Request node that needs to be stopped.

  2. Choose Stop.

Note

This will stop only the STAF executable which is currently waiting for a response from STAFProc.

Stop loading a response

To stop loading a response, click button in the toolbar.

Finding a machine

To find a machine across the pools, ToolsFind Machine.

In the Find Machine dialog,

  1. Enter a name in the Machine name textbox. If the name matches any one of the machine names, a table with the matching machine names and pool names will display below the textbox.

  2. Select the machine name row in that table.

  3. To find the machine, Click the Locate button.

Choosing a pool

There are two ways to choose a pool,

  1. Select a tab from the Pool tab.

  2. Click the List all pools button and choose a pool from the popup menu.

Tip

You may need to use the Pool navigation buttons to navigate around the hidden pools to select a tab.

History

In STAF GUI, history is a collection of requests and responses. STAF GUI can store history locally for later review. If you enable history, then the history will store permanently. Otherwise, it will be available for the current session only. Closing the application will cause it to be lost.

Enabling history

There are three ways to enable history:

  1. Choose HistoryHistory (Ctrl+H).

  2. In the Statusbar,

    1. Right-click on the history icon.

    2. Choose History.

  3. Choose ToolsPreference (Ctrl+R).

    In the Preference window, in the History tabbed section,

    1. Select the Enable history checkbox.

    2. Click the Close button.

Viewing a history

There are two ways to view a history:

  1. In the toolbar,

    1. Click the List all requests button.

    2. Select a request from the popup menu.

  2. In the other way,

    1. In the Command pane, if necessary expand the machine and service whose history you want to view.

    2. In the Command pane, select a command under the service.

    3. Select a request from the Submit drop-down combination box.

Note

List all requests lists only the history of the machines in the current pool. Changing the current pool will change this list.

Navigating history

Two ways to navigate history:

  1. In the toolbar,

    • To view previous history, click .

    • To view next history, click .

  2. In the menubar

    • Windows and Linux,

      • To view previous history, choose HistoryBack (Alt+left arrow).

      • To view the next history, choose HistoryForward (Alt+right arrow).

    • Mac OS X,

      • To view the previous history, choose HistoryBack (Command+[).

      • To view the next history, choose HistoryForward (Command+]).

Narrowing down a history

You can narrow down history for a machine, service, or command.

  • Machine

    In the Command pane, select a machine. The Submit drop-down combination box lists all the history for that machine.

  • Service

    In the Command pane, select a service. The Submit drop-down combination box lists all the history for that service.

  • Command

    In the Command pane, select a command. The Submit drop-down combination box lists all the history for that command.

Deleting session history

To delete session history, in the toolbar, click .

Deleting history

To delete history, choose HistoryShow All History (Ctrl+Shift+H).

In the History window,

  1. In the Command pane, if necessary, expand the pool, machine, and service.

  2. To list history in the History pane, select pool, machine, service, or command. This will narrow down history in accordance with the selection.

  3. In the History pane, select the history that you want to delete.

  4. There are two ways to delete,

    1. Press the Delete key.

    2. Right-click on the selection, choose Delete History.

Working with text

Working with text (selecting, cutting, copying, pasting and deleting) in STAF GUI is similar to working with text in any other application. You can use the mouse or the keyboard for these operations. You can also copy text from other sources, such as Web pages, and paste it into STAF GUI.

Selecting, cutting, copying, pasting and deleting text

  • All text boxes and drop-down combination boxes allow all operations.

  • The Response pane, however, allows only selecting and copying operations.

Finding text

You can use the find feature in the Response pane for searching text. To display the find toolbar, choose EditFind (Ctrl+F).

  1. Enter a word or phrase in the Find text box.

  2. Select the Match case check box for a case-sensitive search.

  3. Click Next. To proceed from top to bottom, click the button again or choose EditFind Again (Ctrl+G). To search in the opposite direction, click Previous.

Chapter 5. Maintaining QuickSTAF

Backing up application data

To backup application data, choose FileBackup.

In the Backup Application Data dialog,

  • Windows

    The default file name quickstaf displays in the File name drop-down combination box.

    1. If necessary, specify a name in the File name drop-down combination box.

    2. Click the Save button. The statusbar will display the progress of the backup. Wait until it completes.

  • Linux

    The default file name quickstaf displays in the Name textbox.

    1. If necessary, specify a name in the Name textbox.

    2. To save, click the Save button. The statusbar will display the progress of the backup. Wait until it completes.

  • Mac OS X

    The default file name quickstaf.dat displays in the Save As textbox.

    1. If necessary, specify a name in the Save As textbox.

    2. To save, click the Save button. The statusbar will display the progress of the backup. Wait until it completes.

Restoring application data

To restore application data, choose FileRestore.

In the Restore Application Data dialog,

  1. Select an application data file.

  2. Click the Open button.

  3. In a new Restore Application Data dialog, Click the OK button. The statusbar will display the progress of the restore. Wait until it completes.

Backing up history data

To backup history data, choose HistoryShow All History (Ctrl+Shift+H).

In the History window,

Backup and RestoreBackup.

In the Backup History Data dialog,

  • Windows

    The default file name quickstafhistory displays in the File name drop-down combination box.

    1. If necessary, specify a name in the File name drop-down combination box.

    2. To save, click the Save button. The statusbar will display the progress of the backup. Wait until it completes.

  • Linux

    The default file name quickstafhistory displays in the Name textbox.

    1. If necessary, specify a name in the Name textbox.

    2. To save, click Save button. The statusbar will display the progress of the backup. Wait until it completes.

  • Mac OS X

    A default file name quickstafhistory.dat displays in the Save As textbox.

    1. If necessary, specify a name in the Save As textbox.

    2. To save, click the Save button. The statusbar will display the progress of the backup. Wait until it completes.

Restoring history data

To restore history data, choose HistoryShow All History (Ctrl+Shift+H).

In the History window, Backup and RestoreRestore.

In the Restore History Data dialog,

  1. Select a history data file.

  2. Click the Open button.

  3. In a new Restore History Data dialog, Click the OK button. The statusbar will display the progress of the restore. Wait until it completes.

Appendix A. Keyboard shortcuts

You need both a keyboard and a pointing device to use STAF GUI. However, you can use the keyboard alone to perform some of the most common tasks. This appendix lists the keyboard shortcuts.

Choosing menu items

You can open the menus by pressing the underlined character together with the Alt key. Once the menu is opened, you can access menu items by pressing the underlined character key.

Using shortcut keys in dialogs

When you open any dialog, one element (such as a button, a text box, an entry in a list box, or a checkbox) is indicated by a dotted box around the element, by a blinking cursor or by highlighting. This element is said to have the focus on it.

Press the Tab key to change the focus from one element or area to the next, or press Shift+Tab to go in the reverse direction.

  • If the focal point is a button, pressing Enter runs it as if you had clicked it with the mouse.

  • If the focal point is a checkbox, pressing the spacebar changes the toggled status.

  • If the focal point is a radio button, pressing the arrow keys changes the selected status.

Press Esc to close the dialog without saving changes.

Shortcut keys

Table A.1. General Shortcut keys
Keyboard Shortcuts Results
Tab Advances focus to the next element
Shift+Tab Moves the focus to the previous element
Enter Activates the focused button
spacebar Toggles the focused checkbox
arrowkeys Changes the selected states of radio group
Ctrl+S Saves the current response
Ctrl+P Prints the current response
Ctrl+X Cuts the selected text and keeps that in clipboard
Ctrl+C Copies the selected text
Ctrl+V Pastes from the clipboard
Del Deletes the selected text
Ctrl+F Shows Find toolbar
Ctrl+G Finds again
Ctrl+A Selects all texts
Ctrl+L Shows add pool dialog
Ctrl+E Shows edit pool dialog
Ctrl+M Shows add machine dialog
Alt+left arrow Shows one request backward in history (for Windows and Linux)
Alt+right arrow Shows one request forward in history (for Windows and Linux)
Command+] Shows one request backward in history (for Mac OS X)
Command+[ Shows one request forward in history (for Mac OS X)
Shift+Ctrl+H Shows history window (for Windows and Linux)
Ctrl+H Toggles history enable state
Ctrl+R Shows preference window

Appendix B. Common error messages

STAF not in PATH environment variable

STAF executable was not in the PATH environment variable. In order to use STAF GUI, this must be set. See STAF V3 User's Guide for instructions on setting PATH environment variable for your operating system.

  • Windows

  • Linux and MAC OS X

STAFProc not running

STAF GUI sends a request on a machine where STAF demon process, called STAFProc, wasn't running. In order to use STAF GUI, it must be running on the same machine. This is often the case where you send a request to a non-existent instance name. See STAF V3 User's Guide for instructions on starting STAFProc.

There is another such error occurs when you send a request to a non-existance static handle number.

STAF machine unreachable

The machine is not reachable from the current machine. Check your network connection or machine name.

Service does not provide HELP command

The current service does not provide the HELP command. You can't use STAF GUI to send a request to this service.

Application restore file error

The file selected to restore the application data is not valid. Use files from previous backup of the application.

History restore file error

The file selected to restore the history data is not valid. Use files from previous backup of the history.

Application data file error

The application file or directory was deleted. Restart the application and restore from the latest application data backup.

History data file error

The history file or directory was deleted. Restart the application and restore from the latest history data backup.

No Endpoint, Service or Command exists error

This error occurs when trying to submit a request by directly typing in the Submit drop-down combination box. This is neither supported nor recommended. Always use the Command pane and Option pane to create a request string.

Response conversion error

An error occurred when converting an HTML table from STAF raw. Use STAF default or verbose. See the section called “Editing a pool” for instructions.

General submitting error

A general error prevents you from submitting a request. Restarting the application may solve this error.

Command options error

Locally stored service help has syntax errors, or the application data file was manually edited. This is neither supported nor recommended. Update the service.

Remote machine not supported error

This error occurs when you are trying to add a remote machine in the QuickSTAF Standalone edition. Use QuickSTAF Network.

Appendix C. Setting environment variables

In STAF, you set environment variables to change the behavior of a request and response dynamically. In STAF GUI, you use pool settings for this purpose. See the section called “Adding a pool” for instructions.

Supported environment variables

STAF environment variables are listed in the Supported environment variables table. STAF_OLDCLI is not supported since STAF GUI does not support any STAF version below 3.0. STAF_DEBUG_21, STAF_THREAD_STACK_SIZE and STAF_TEMP_DIR are not supported since these are STAFProc environment variables. STAF_PRINT_NO_TABLES is not supported since you can achieve the same effect by setting verbose mode. See the section called “Adding a pool” for more details.

Table C.1. Supported environment variables
Environment variable Supported status
STAF_DEBUG_21 N/A
STAF_IGNORE_INDIRECT_OBJECTS Yes
STAF_INSTANCE_NAME Yes
STAF_OLDCLI N/A
STAF_PRINT_MODE Yes
STAF_PRINT_NO_TABLES No
STAF_QUIET_MODE Yes
STAF_REPLACE_NULLS Yes
STAF_STATIC_HANDLE Yes
STAF_TABLE_LINES_PER_RECORD Yes
STAF_TEMP_DIR N/A
STAF_THREAD_STACK_SIZE N/A

Appendix D. Technical background

In order to use STAF GUI, it is not necessary that you understand how it works. This background information describes how it interacts with STAF demon process, called STAFProc, and the necessary steps it takes to complete the interaction.

STAF GUI uses STAF command line client executable, called STAF, to submit a request. It doesn't use STAF API. In fact, the executable uses STAF API to interact with STAFProc. Therefore, to use STAF GUI, this executable must be in the PATH environment variable.

In order to work with different versions of STAF, STAF GUI must be binary compatible with all the versions. For this reason, it uses STAF executable instead of directly using STAF API. Therefore, any future changes in STAF API will not affect the functionality of STAF GUI.

STAF GUI needs to know the commands and options of a service before you send a request. In this respect, it is like your sending a HELP request to know how to use a service. In other words, STAF GUI needs to be set up before it may be used. In the setup stage, you add the machines and their services that you want to send requests.

When you add or update services, STAF GUI sends a LIST request to the Service service to display available services.

When you select a service to add or update:

  1. It sends a HELP request to that service.

  2. It automatically finds all the commands and options from the service help.

  3. It sends a VERSION request if service provides such a command.

  4. It stores the service name, service help, and version locally.

When you start STAF GUI the next time, it uses the locally stored service help to find commands and options.

When you select a service to update:

  1. It sends a HELP request to that service.

  2. It compares the service help with the locally stored one. If they differ, then it copies the new commands and options and discards the old one.

  3. It sends a VERSION request if service provides such a command.

  4. It updates the service help and version if necessary.

Important

STAF GUI does not automatically update a service unless you ask for it. As a result, when you install or remove a new version of the service, the information on the machine may differ from STAF GUI.

In order to submit a request you need to compose one. First, you select a command in the Command pane. If the command has any options, then those options will display in the Option pane with the default values. Second, you specify values for options in the Option pane. If you specify all the necessary options, the Submit button becomes enabled. In addition, the composed request string displays in the Submit drop-down combination box. You submit this request by clicking the Submit button.

When you submit a request while history is in the enabled state, it stores the result locally in the specified format. Otherwise, closing STAF GUI will clear all results.

Appendix E. Modifying service help

In order to use STAF GUI you do not need to modify any of the service help. This feature is provided for the following purposes only:

  1. To correct any syntax error or positional invalidity in service help.

  2. To design a new service by trying out various ways to provide a help.

Moreover, the changes that you are going to make in service help may not work at all since the service may not support the command or options that were specified. Therefore, you should be clear about your purpose before you edit a service help.

This section explains how to edit service help and correct any syntax errors.

Editing service help

In the Edit Service Help dialog, the response header displays in an un-editable textbox and statements display in an editable textbox.

  1. Edit the statements in the textbox.

  2. In future, if you do not want to make any changes, select the Do not show next time check box.

  3. Accept or Cancel:

    • To discard the changes, click the Reset button.

    • To accept the changes, click the Accept button.

Meanings of syntax errors

This section explains the meanings of syntax errors in service help and provides the methods of correcting them. Line numbers in error descriptions begin from the start of the statement block. See Appendix F, Service help specification for more information about the statement block.

Unexpected Command

Missing > and ] characters cause this error.

In Figure E.1, “A missing ']'” error description displays syntax error, unexpected COMMAND at line:5 column: 3. At line 5 and column 3 is a PUT command. This implies, that a command starts before the previous statement ends. A missing ] character indicates that the statement continues on the next line. But the next line starts with the PUT command. Therefore, if the error description starts with unexpected COMMAND, then look for a missing or unbalanced character before the specified line number.

Figure E.1. A missing ']'


Unexpected character

Missing < and [ characters are the cause of this error.

In Figure E.2, “A missing '['” error description displays syntax error, unexpected ']', expecting end of service help or COMMAND at line: 3 column: 36. That implies, an extra ] character appears in the statement. An extra character in a statement indicates either that an extra or a right-paired (in this case it is [) character is missing from the statement. Therefore, if the error description starts with unexpected ']' (or '>'), then either remove that character or find a position for a right-paired character.

Figure E.2. A missing '['


Correcting service help errors when adding services

In the Correct Service Help Error dialog, the error description displays in the first row. After that, the response header displays in an un-editable textbox and statements display in an editable textbox.

  1. Correct the syntax error in the textbox. See the section called “Meanings of syntax errors” for instructions.

  2. Accept or Cancel:

    • To discard the changes, click the Reset button.

    • To fix later, click the Fix later button.

    • To accept, click the Accept button.

Correcting service help errors when updating services

In the Correct Service Help Error dialog, the error description displays in the first row. After that, the response header displays in an un-editable textbox and statements display in an editable textbox.

  1. Correct the syntax error in the textbox. See the section called “Meanings of syntax errors” for the method of correction.

  2. Accept or Cancel:

    • To discard the corrections, click the Reset button.

    • To accept, click the Accept button.

Appendix F. Service help specification

This section explains how to write a service help for a new service so that users can send requests to your service using STAF GUI. Appendix D, Technical background describes how STAF GUI uses service help to create a request string.

Service help is a response of a HELP request to a service. As is shown in Figure F.1, “NAMEDCOUNTER service help”, it contains a response header and statements. You read these statements in order to know how to use the service. STAF GUI converts these statements into GUI elements to display in the Command pane and Option pane. For this conversion to work, service help has to be in the proper format.

Figure F.1. NAMEDCOUNTER service help


First, we specify the proper service help format. Second, we specify how converted GUI elements display in the Option pane. Finally, we specify the sizes of the textbox elements in the Option pane.

Service help format

This format has to satisfy the following requirements:

  1. STAF GUI has to know the start and end position of statements, also called statement blocks, within the service help.

  2. The statements must be error free for conversion.

The first is called positional validity and the second, syntax validity.

Positional validity

It is necessary to specify a valid start and end position in service help for statements to be read. First, we look at a few examples from STAF services. Observe line number four in each of these examples. It is either an empty line or first statement. Also observe the last line. It is either an empty line, the last statement, or a portion of the statement if the last statement spans more than one line.

    [bash@host dir]$ STAF LOCAL DELAY HELP
  1 Response
  2 --------
  3 DELAY Service Help
  4 1
  5 DELAY <Number>[s|m|h|d|w]
  6 HELP
  7 2


    [bash@host dir]$ STAF LOCAL REG HELP
  1 Response
  2 --------
  3 *** REG Service Help ***
  4 3
  5 REGISTER [TYPE <Name>] DATA <Data>
  6 
  7 HELP4


    [bash@host dir]$ STAF LOCAL CRON HELP
  1 Response
  2 --------
  3 Cron Service Help
  4 REGISTER   [DESCRIPTION <description>]5
  5            MACHINE <machine> | PYTHONMACHINE <machine>
  6            SERVICE <service> | PYTHONSERVICE <machine>
  7            REQUEST <request> | PYTHONREQUEST <request>
  8            [PREPARE <script>]
  9            [MINUTE <minute>] [HOUR <hour>]
 10            [DAY <day>] [MONTH <month>]
 11            [WEEKDAY <weekday>]
 12            [ONCE]
 13            [ENABLED | DISABLED]
 14 UNREGISTER ID <registrationID>
 15 LIST       [MACHINE <machine>] [LONG | SHORT]
 16 TRIGGER    ID <registrationID> [SCRIPT <Python code>]...
 17 ENABLE     ID <registrationID>
 18 DISABLE    ID <registrationID>
 19 VERSION    [JYTHON]
 20 HELP6
	

1 3 5

Beginning of a statement in service help

2 4 6

Ending of a statement in service help

From these examples (and all of the STAF internal and external services), we conclude the positional validity as follows: Statements in service help start at line number four and end at the end of response.

Two kinds of errors occur when the service help is in an invalid position:

  1. Exclusion of a statement

  2. Inclusion of header text

Exclusion of a statement occurs when the statement starts before line number four in the service help.

Inclusion of text occurs when the response header comes after line number four in the service help.

STAF GUI can't detect these errors. If one occurs, you need to interfere with the service help conversion process and make the correction. See the section called “Editing service help before adding or updating services” for instructions.

Syntax validity

Syntax validity specifies the grammar of a statement as defined by the STAF V3 User's Guide. It says:

 

When examining the syntax statements for each service, keep the following rules in mind.

  • Unadorned options are required

  • Options or values surrounded by angle brackets, e.g. < and >, are required.

  • Options or values surrounded by square brackets, e.g. [ and ] , are not required.

  • Options in a group are separated by a vertical bar. Only one of the options in a group may be specified.

 
 --STAF V3 User's Guide

In addition to the preceding rules, observe the following rules for statements:

  • Every statement must start with a command.

  • A statement may span multiple lines where those additional lines start with space characters.

  • A command may appear in different statements.

All STAF internal service help has valid syntax. At the time of this writing, the latest version is 3.4.5. All STAF external service help also has valid syntax. At the time of this writing, the latest versions are:

Table F.1. External services
External service Version
CRON 3.3.8
EMAIL 3.3.5
EVENT 3.1.4
EVENTMANAGER 3.3.8
FSEXT 3.0.2
FTP 1.0.3
HTTP 3.0.2
LOG 3.4.0
MISC 3.4.5
MONITOR 3.4.0
NAMEDCOUNTER 3.0.2
NAMESPACE 1.0.2
RESPOOL 3.4.1
STAX 3.4.5
SXE 3.0.3
TIMER 3.0.3
ZIP 3.4.0

STAF GUI can detect syntax errors in service help. If one occurs when you add a service, you will be prompted to make a correction. You can also interfere with the service help the conversion process. See the section called “Editing service help before adding or updating services” for instructions.

Follow the guidelines specified in the STAF V3 User's Guide and here when you write a service help. See the design of internal and external service help, as examples. Also see how these examples are designed to meet the functionality provided by the service.

Service help to GUI element map

Statements in service help have two components. These are commands and its options. After the conversion:

  1. Commands in the service help become child nodes of service in the Command pane.

  2. Options become GUI elements which will display in the Option pane when you select the command.

Example F.1. DEMO service help

Response
--------
DEMO Service Help

RESET  FORCE
RANDOM <REG | GEN>
LOG    GLOBAL | MACHINE
SWITCH [ENABLED | DISABLED]
REPEAT [ONCE]
READ   <Message>...
HELP

	

The following Table F.2, “DEMO service help conversion” shows the conversion of command and options specified in Example F.1, “DEMO service help”.

Table F.2. DEMO service help conversion
Statement Conversion
RESET FORCE
RANDOM <REG | GEN>
LOG GLOBAL | MACHINE
SWITCH [ENABLED | DISABLED]
REPEAT [ONCE]
READ <Message>...

The following Table F.3, “Options-GUI elements mapping” shows the corresponding GUI element for the options specified in Example F.1, “DEMO service help”.

Table F.3. Options-GUI elements mapping
Option GUI element Type
FORCE
A label converts into a field.
<REG | GEN>
This is converted into a drop-down list which contains REG and GEN. You must select one of the items. The first one is selected by default.
GLOBAL | MACHINES
This is converted into a drop-down list which contains GLOBAL and MACHINES. You must select one of the items. The first one is selected by default.
[ENABLED | DISABLED]
This is converted into a drop-down list which contains an empty string, ENABLED and DISABLED. Empty string is selected by default, The empty string does not contribute to anything in a request string.
[ONCE]
This is converted into a checkbox. To include this option in the request string, select this checkbox.
<Message>
This is converted into a textbox. You specify a value in this textbox.
...
This is converted into two buttons. Initially only the + button will be displayed. To specify recurring options, click the + button. The block of GUI elements will be displayed with a - button. To remove these options, click the - button.

Displaying elements dynamically

Child options are also options of a command that depends on the selection of the parent option. These options are not displayed until you select or choose the parent option. Therefore, the options are displayed only when necessary.

Figure F.2. Parent and child options in a service help


Figure F.3. Parent option not selected


Figure F.4. Parent option selected


Creating elements dynamically

You create recurring elements dynamically. For example, as in Figure F.5, “Recurring option in a service help”, you may need to specify more than one file as an attachment. For each file, an identical block of elements will be needed. Click the + button to create those block of elements. You can create as many block of elements as necessary. Click the - button to remove the last block of elements.

Figure F.5. Recurring option in a service help

[BINARYATTACHMENT <File>]...
      

Figure F.6. Recurring option after conversion


Figure F.7. After specifying the first value


Figure F.8. After creating the second block of elements


Figure F.9. After specifying the second value


Figure F.10. After removing the second block of elements


Layout of elements

When statements are converted into GUI elements STAF GUI tries to lay out the elements as WYSIWYG (what you see is what you get). As shown in Table F.4, “EVENT REGISTER options”, STAF GUI will lay out the resulting GUI elements as they appear in the service help.

Table F.4. EVENT REGISTER options
TYPE <Type> [SUBTYPE <Subtype>]...
[ACKNOWLEDGETIMEOUT <Timeout>] [MAXATTEMPTS <Number>]
[PRIORITY <Number>] [PRIORITYDELTA <Number>]
[BYNAME | BYHANDLE]

Repeating commands in service help

Multiple commands with the same name in service help will yield only one node with that name under the service node in Command pane. Their options are treated as if they were presented in service help with '|' in between. Consequently, they are converted into a drop-down list.

Figure F.11. Event has multiple LIST command


Extra space characters in service help

STAF GUI discards extra space characters in service help before it converts into GUI elements, leaving only one space character between GUI elements. However, if there is no space character in between any two options, the converted GUI elements will be laid out next to each other without any space between.

Determining textbox size

Textbox sizes in the Option pane are determined by the values in service help options. There are three different sizes of textbox displays in the Option pane.

  1. Regular single line input for numbers with 70px width.

  2. Regular single line input for text with 150px width.

  3. Larger multi-line input for text with 200px width and 100px height.

If the option has the case insensitive values number, or size within the < and >, then the number textbox will be displayed.

If the option has the case insensitive values script, code and data anywhere within the < and >, then the multi-line textbox will be displayed.

For example, all of the following options will convert into multi-line textboxes. <Description>, <Python script>, <Java code> and <Xml data>. In the first example, the word Description contains script.

Appendix G. HTML table format specification

STAF GUI provides HTML table format for responses, in addition to STAF default, verbose and raw. This format is converted from STAF raw. Therefore, the response should be in raw format.

Every conversion of a raw format is into a table format. STAF V3 User's Guide defines the raw format as structured data. Conversion from any type of structured data occurs in a table form.

In the following examples, we compare the table format with STAF default. For brevity, response headers have been left out from the table formats. Example requests are taken from the STAF V3 User's Guide.

Example G.1. Simple list

If the response is a simple list, then a single column table will be generated.

C:\>STAF LOCAL FS LIST DIRECTORY C:\STAF
Response
--------
bin
codepage
data
docs
include
install.properties
lib
LICENSE.htm
NOTICES.htm
samples
services
STAFEnv.bat
STAFInstall.log
startSTAFProc.bat
startSTAFProc.ico
Uninstall_STAF

Table G.1. Simple list table
bin
codepage
data
docs
include
install.properties
lib
LICENSE.htm
NOTICES.htm
samples
services
STAFEnv.bat
STAFInstall.log
startSTAFProc.bat
startSTAFProc.ico
Uninstall_STAF

Example G.2. Simple map

If the response is a simple map, then a two column table will be generated.

C:\>STAF LOCAL MONITOR LIST SETTINGS
Response
--------
Max Record Size    : 1024
Resolve Message    : Disabled
Resolve Message Var: Disabled
    
Table G.2. Simple map table
Max Record Size1024
Resolve MessageDisabled
Resolve Message VarDisabled

Example G.3. List of map

If the response is a list of map, then a multi-column table with header will be generated.

[bash@host dir]$ STAF local handle list handles
Response
--------
Handle Handle Name                     State      Last Used Date-Time
------ ------------------------------- ---------- -------------------
1      STAF_Process                    InProcess  20110409-07:34:48
2      STAF/Service/STAFServiceLoader1 InProcess  20110409-07:34:48
3      STAF/Service/MONITOR            InProcess  20110409-07:34:48
4      STAF/Service/LOG                InProcess  20110409-07:34:48
5      STAF/Service/RESPOOL            InProcess  20110409-07:34:48
6      STAF/Service/ZIP                InProcess  20110409-07:34:48
7      STAF/Client                     Registered 20110415-22:00:00
    
Table G.3. List of map table
HandleHandle NameStateLast Used Date-Time
1STAF_ProcessInProcess20110409-07:34:48
2STAF/Service/STAFServiceLoader1InProcess20110409-07:34:48
3STAF/Service/MONITORInProcess20110409-07:34:48
4STAF/Service/LOGInProcess20110409-07:34:48
5STAF/Service/RESPOOLInProcess20110409-07:34:48
6STAF/Service/ZIPInProcess20110409-07:34:48
12STAF/ClientRegistered20110415-22:08:02

Example G.4. Complex

If the response is more complex, then a two column table will be generated. If one data type is included in another, the first column of the data, the one that is included, will be indented. The amount of indentation is proportional to the inclusion hierarchy. If the value of a map is not simple, then the name of that map spans both columns and the values come after the name column. A square bracket delimits a list to differentiate it from a map. Each item of the list is separated by an empty line.

C:\>STAF LOCAL SEM QUERY EVENT Test
Response
--------
{
  State      : Reset
  Last Posted: {
    Machine    : IBM-7E43361B084
    Handle Name: STAF/Client
    Handle     : 154
    User       : none://anonymous
    Endpoint   : local://local
    Date-Time  : 20110415-17:00:52
  }
  Last Reset : {
    Machine    : IBM-7E43361B084
    Handle Name: STAF/Client
    Handle     : 154
    User       : none://anonymous
    Endpoint   : local://local
    Date-Time  : 20110415-17:00:52
  }
  Waiters    : [
    {
      Machine    : IBM-7E43361B084
      Handle Name: STAF/Client
      Handle     : 164
      User       : none://anonymous
      Endpoint   : local://local
      Date-Time  : 20110415-17:12:09
    }
  ]
}
    

Table G.4. Complex table
StateReset
Last Posted
  MachineIBM-7E43361B084
  Handle NameSTAF/Client
  Handle154
  Usernone://anonymous
  Endpointlocal://local
  Date-Time20110415-17:00:52
Last Reset
  MachineIBM-7E43361B084
  Handle NameSTAF/Client
  Handle154
  Usernone://anonymous
  Endpointlocal://local
  Date-Time20110415-17:00:52
Waiters
  [
    MachineIBM-7E43361B084
    Handle NameSTAF/Client
    Handle164
    Usernone://anonymous
    Endpointlocal://local
    Date-Time20110415-17:12:09
  ]

Glossary

Command

A command is a functionality provided by a service to accomplish a task.

Endpoint

See Machine.

Machine

A computer where STAF runs as a demon process (called STAFProc).

Option

Optional arguments for a command.

Pool

Contains a collection of machines. It also has settings of instance name, handle number and print mode for every request.

Request

A request is what service accepts on a machine.

Request string

A command followed by options in a request.

Response

A response is a result of a request.

Service

Services are what provide all the capability of STAF in a machine.

Session

A period of time in between STAF GUI starts and ends.

Index

F

find, Finding text
find again, Finding text