Appendix F. Service help specification

Table of Contents

Service help format
Service help to GUI element map
Determining textbox size

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>
  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>
 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
FSEXT 3.0.2
FTP 1.0.3
HTTP 3.0.2
LOG 3.4.0
MISC 3.4.5
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.