A1. Calling Wizard Routines

Calling Wizard Subroutines from your BASIC code
   Getting Input
   Key Codes
Drawing Boxes
Wizard Help Menu
Display Wizard Help
Printing Wizard Help
Wizard Word Processing

Calling Wizard Subroutines from your BASIC code

Sometimes you may need to create your own basic programs rather than use a Wizard screen. In order to enhance what you are able to do, Wizard allows you to call some of its routines from your own programs. This section of the manual is designed to help those of you who want to create such programs or alter any existing BASIC programs on your system.

To be able to use these Wizard functions from your own basic programs, you first need to include some code. At the beginning of your program, before any other code is executed (although it may appear after the initial comment lines) you must include the following:

   $INCLUDE WUTIL BASIC.INCLUDE

This contains declarations and setups for Wizard terminal and keyboard definitions. It includes some COMMON statements which need to precede any of your own COMMON code for Wizard subroutines to function correctly.

Note: Subroutines
If the program you are working on is a subroutine called from another BASIC program, you'll need to include the above code in the calling (main) program, and in its place in the subroutine you should include:

   $INCLUDE WUTIL COMS

and if you want to use the keyboard equates (see below) you must also subsequently include the line:

   $INCLUDE WUTIL KEYCODES

Getting Input

There are primarily two input routines which you have available to you from Wizard, each of which is described here. Both are subroutines, and can be called from any program where the above includes have been correctly installed.

Single Character Input

The simplest of these routines returns the ASCII code for the key pressed (if it was in the range 32 to 126) or a special Wizard code otherwise. It returns one key at a time, and is called as follows:

   CALL WizCH( var )

Here, var returns the ASCII code of the key pressed. If you want to compare it to the keycodes to determine whether, for example, <Up> was pressed, you'd need to do a test something like

   IF CHAR(var) = Up THEN

(Refer to the section below on keycodes for more information.)

Single Line Input

If you want to replace an entire INPUT statement in a BASIC program, you can use the code:

   CALL WizInp( l, x, y, e, i, c )

The parameters in the subroutine are:

l	The length of the input field.
x	The 'x' coordinate or column for the start of the input field.
y	The 'y' coordinate or row for the start of the input field.
e	If this is '1', input will be echoed to the screen as it is entered, otherwise it will not be echoed.
i	The user's input will be returned to the program in this variable. This should be set to null prior to calling this routine.
c	This is the colour code. For BASIC programs you should leave this as '0'.

The routine will return whatever the user entered. If, however, the user entered a function key or an up-arrow key (etc.) during the entry of some text, that function key code will be returned before the completion of data entry on that field and it will be in 'i<1>' (attribute 1 of the 'i' variable), while the text the user was entering will be in 'i<2>'.

If you wish to test the input against the key codes (see below), you may do so directly, for example,

   IF i<1> = Up THEN ...

Keycodes

Included in the Wizard setup is a set of key code equates to help you test the keys which have been pressed. The codes you can test against are:

Keycode Meaning

Function Keys

Your basic program may also set its own function key definitions by adjusting the FUNC array (somewhere after the above '$INCLUDE' statements in your program).

If, for example, you want to set function key 4 to be equal to the text 'HELLO', all you need is the code

   FUNC(4)='HELLO'

somewhere prior to calling the 'WizInp()' routine described above. Note that to set the function keys + <shift> key, you set the elements in the FUNC array numbered 13 to 24 (so <shift> + function key 1 is set by FUNC(13)).

Note that this setup works only for the WizInp() routine, which returns the function key text in attribute 1 of the input variable and any other text in attribute 2 of the input variable (see above).

If you use the single key input routine WizCH(), you may check for function keys being pressed by testing against standards set up in the INCLUDEs above, these being:

   CALL WizCH( Key )
   Key=CHAR(Key)
   BEGIN CASE
      CASE Key = f1
         * function key 1 was pressed.
      CASE Key = f5
         * function key 5 was pressed.
      CASE Key = sf4
         * <shift> func. key 4 was pressed.
   END CASE

(i.e. the codes 'f1' to 'f12' and 'sf1' to 'sf12' are all set up in the INCLUDE code segments described above.)

Drawing Boxes

You can also use the Wizard routine to draw boxes once you have made the above includes. All box drawing is done by one routine, which is:

   CALL WizBox( x, y, w, d, h, t, c )

The parameters required by this routine are:

   0 0 x 0 0 0 x x

Wizard Help Menu

Whenever the data entry operator requests help from a Wizard Screen or from the Menu the first routine that is called is the WizardHelp routine. This subroutine will display a list of Help options from which the operator may select Help.

The first Help item is the current Field or Menu option.

   CALL WizardHelp( o, fn, id, c, r, w, d, rd, col, bdc )

The parameters for this subroutine are:

The File Name (fn) is opened and then the Help Item is read using the Help Item Id (id). If the Help Item has M in attribute <1> then it is a Menu type. If it is not a Menu type then it must be a Help Item. Help items are passed to the Wizard subroutine DisplayHelp.

Menu types have the following structure:

The ] (square bracket) is used to represent a Multi-Value mark and the space either side is for clarity only.

A Menu type could look like:

   001 M
   002 21 ] 2
   003 Screen Help
   004 Field name ] Function Keys ] Wizard Commands ] On Line Manual
   005 21 ] 21 ] 21 ]
   006 3 ] 3 ] 3 ]
   007 9 ]  ] 9 ]
   008 WHELP ]  ] WHELP ]
   009 SetWizMenu.MENU.NAME ] FUNCKEYS ] SCREEN ] OLM

Where there is no data (eg. No column, row or depth for the On Line Manual and no depth for Function Keys) WizardHelp() will use default values.

The Menu type item is read into your Wizard Screens before Entry time:

   READ HelpMenu FROM HELP.FV , 'WS' ELSE HelpMenu=''

The HELP.FV would be WIZHELP unless you change it from the Screen Generator using the EG Command. If you do change the Help file then copy the item WS to your new Help file.

The Menu type for the Wizard Menus is WIZ.MENU from the WHELP file.

All Wizard Screens supplied by General Automation use the Help file WHELP and the item WS in WHELP is the one shown above, the only difference is the WS item in WIZHELP does not have the On Line Manual in it.

When the operator makes a selection from the Help menu and the option id is FUNCKEYS or OLM then DisplayHelp will display the Function Keys or execute the On Line Manual. If the selection is not one of these then DisplayHelp will call itself passing the details from the Menu item.

For example:

o, w, rd, col, bdc are unchanged

   CALL WizardHelp( o, fn, id, c, r, w, d, rd, col, bdc )

This allows you to have a Help Item that is a menu of other Help items. The Maximum number of options on a Menu type is 9.

If you wish to only have the Help from the current Field or option from the Menu displayed then you should change the items WS in WHELP and WIZHELP and the WIZ.HELP item in WHELP to only have the first 3 attributes, all others may be deleted.

Note DisplayHelp() is a recursive subroutine (ie. it calls itself)

If the Help item is a Menu type then WizardHelp() will display a list of Help options to the operator. If the Help item is not a Menu type then WizardHelp() will call DisplayHelp() passing the correct information.

Display Wizard Help

Whenever Wizard displays a Help item it uses the routine DisplayHelp(). This subroutine must have a number of parameters passed, including the Help Item being displayed.

   CALL DisplayHelp( o, fn, id, c, r, w, d, rd, col, bdc )

The parameters passed to this subroutine are:

If the Help Item (id) is null then this routine will display a default Help item called NOHELP from the WHELP file.

You may edit the Help item if your security level is 8 or more by entry of U for update or by pressing <F5>. When you edit Help Items you will be in the WizWP() subroutine.

The structure of a Help item is:

The Tab/Paragraph flags are t and p respectively, in Windows terms the Tab is the same but the Paragraph tab works like an Indent. You may change these to all Paragraph if you wish. The Tab/Paragraph ASCII character is 244.

You may Bold/Unbold words or phrases using the <Shift> + <F8>. The Bold/Unbold ASCII character is 226.

Attribute <6> may contain a Multi-Valued list of Help Ids that are added to the text in the current help item. These Help Ids must be items in the current Help File (e), these linked help items may also have Help Ids in <6>.

When maintaining a Help item that has Linked help, the operator will only be able to change the text <5> in the current item, not the ones that are Linked.

This will allow you to keep the original, common or very important Help safe, the operators may add/change only the text in attribute <5>.

Attribute <7> contains Multi-Valued lower case words and/or phrases that have been indexed. If there are any indexes then DisplayHelp() will allow you to hit the <Tab> key and jump from one to the other.

You may enter the letter I or i to view a list of the indexes, if you select a word or phrase then DisplayHelp() will take you to that word or phrase and Tab will jump to the next occurrence. Enter I a second time and then <Esc> or <F10> to cancel this.

When maintaining help you may enter two special commands that DisplayHelp() will use. These are entered as text and must follow the following format:

   #PICTURE HELP {Help File Name} {Help Id}

and

   #PICTURE SCREEN {ScreenId} {Menu Help} {Map Only}

The #PICTURE ... must be on a line by itself with no preceding spaces. The function of these statements is described below:

#PICTURE HELP

The {Help File Name} would typically be WIZHELP and the {Help Id} could be any Help item (Not menu types).

For example:

   #PICTURE HELP WIZHELP APROMPT

This allows you to combine or embed the standard Wizard Screen's Acceptance prompt Help within your Help.

#PICTURE SCREEN

The {Screen Id} is any Wizard Screen (WVD Id).

The {Menu Help} is Y or N. If Y, DisplayHelp() will read an item W2*W.{Screen Id} from the WIZHELP file.

This is the default Menu Help Id for all Wizard Screens.

The {Map Only} is Y or N. If Y, DisplayHelp() will display a picture of the Wizard Screen only. If it is N then you will see all the Field help after the picture of the Screen.

For example:

   #PICTURE SCREEN MY.SCREEN Y N

This allows you to include the help details of an entire Wizard Screen within other Help Items. This is most useful when one Wizard Screen is linked to another Wizard Screen.

Printing Wizard Help

Sometimes you may wish to print or change the format of a Wizard Help item. This can be done by calling the Wizard subroutine WizDocPrint(). This routine will change the format of a Help item from Multi-Valued and Sub-Multi-Valued to a simple attribute list.

   CALL WizDocPrint(HelpItem, TextWidth, StripBold)

The HelpItem is a typical Wizard Help item. On return from WizDocPrint(), HelpItem contains an attributed list of text. The format of the help item is described above.

The TextWidth is an integer and is the new width of the Text.

The StripBold is a flag: 1 = Yes, 0 = No. If 1 then Strip all the Bold/Unbolding characters out of the text. If 0 then leave the Bold/Unbolding characters in the text.

For example:

   READ HelpItem FROM WHELP.FV , 'NOHELP' THEN
      TextWidth=HelpItem<2>    ;* Use current Width
      CALL WizDocPrint(HelpItem, TextWidth, 1)
      Lines=DCOUNT(HelpItem,AM)
      PRINT 'Start'
      FOR Line=1 TO Lines
         PRINT Line:'.. ':HelpItem<Line>
      NEXT Line
      PRINT 'End'
   END

This would give the following output:

   Start
   1..
   2.. No help has been installed for
   3.. this option.  To install help,
   4.. press F5 on your keyboard.
   End

Wizard Word Processing

Sometimes you may have a need to allow the data entry operator to enter notes, comments or remarks or even letters to your customers, suppliers etc. You would also need the ability to format the text with Tabs and Paragraphs and you wish to be able to edit this text using a simple Word Processing tool.

In the above case you could use the WizWP() subroutine. This is the Wizard Word Processor refer to chapter 1 for details on where and how this is currently used by the data entry operators.

You may call this routine as follows:

   CALL WizWP( o, c, r, d, fn, id, col, bdc )

The parameters for the subroutine are:

Also see the discussion on Help Items in Display Wizard Help in this chapter for additional data held in the Help Item

The following will describe two scenarios using WizWP()

1. Writing letters which could be short or quite lengthy. If there is a lot of text to be entered it would be easier to handle each letter as a separate item in a file.

   We will assume that you wish to write letters to your customers and that you have a CUSTOMER file and a CUST.LETTERS file.

   One attribute in the CUSTOMER file is used to store the Multi-Valued list of CUST.LETTERS Ids (the Letters for the given Customer). These Ids are made up from the Customer's Id and the Multi-Value position (or number), these are concatenated with an asterisk * in between:

      IBM*1 ] IBM*2 ] IBM*3 ] ...
   

   Other attributes, in the Customer file, that are also Multi-Valued would control details such as Title, Time and Date created, and sent, Author, etc...

   The following code assumes you are in a Wizard Screen and the code is in both Entry Time and User Defined Global Code Segment.

   Note that we do not lock the CUST.LETTERS file, this is because we have used a Wizard Screen and Wizard has locked the CUSTOMER file for the given Customer Id. This process is assumed to be the only one to maintain the Letters, therefore no one else can access this Customer's letters, as we have already locked this Customer.

   Entry Time

   001 LetterRuler    = 1
   002 LetterRuler<2> = 60
   003 LetterRuler<3> = 5 : VM : 10 : VM : 15 : VM : 20
   004 LetterRuler<4> = t : VM : p  : VM : t  : VM : p
   

   User Defined

   001 120 * Maintain Letters
   002 *------
   003 LetterId=INPUT.IDS 1) : '*' : VMC
   004 New = 0
   005 READV OldText FROM CUST.LETTERS.FV , LetterId , 5 ELSE
   006  WRITE LetterRuler ON CUST.LETTERS.FV , LetterId
   007  OldText=''
   008  New=1
   009 END
   010 *
   011 CALL WizWP(OFFSET, 15, 2, 19, 'CUST.LETTERS', LetterId, HelpCol, BDCol)
   012 *
   013 GOSUB 35100    ;* Re paint the Wizard Screen
   014 READV NewText FROM CUST.LETTERS.FV , LetterId , 5 ELSE NewText=''
   015 IF NewText='' THEN ;* They may have Filed without any text
   016  IF New THEN Del=1 ELSE
   017   IF {It is OKay to Delete} THEN Del=1 ELSE
   018    Del=0
   019    NewText = OldText
   020    Letter = LetterRuler : AM : OldText
   021    WRITE Letter ON CUST.LETTERS.FV , LetterId
   022   END
   023  END
   024  IF Del THEN DELETE CUST.LETTERS.FV , LetterId
   025 END ELSE Del=0
   026 LetterChg=(NewText # OldText)
   027 RETURN
   

   Now you can check if the Letter is New, Deleted (Del) or Changed (LetterChg).

2. Writing Notes or Comments, which typically would not be more than a page. We will use the same CUSTOMER file but this time the text will be stored in attribute <15> in the CUSTOMER file. The Entry Time Code is the same as above.

   User Defined

   001 140 * CALL WizWP for CUSTOMER Comments
   002 *------
   003 OldText = INPUT.ITEMS 1)<15>
   004 CommentRec = LetterRuler : AM : OldText
   005 CommentId = INPUT.IDS 1) : '*' : PORT  ;* Unique Id
   006 WRITE CommentRec ON INPUT.FVS 1) , CommentId
   007 *
   008 CALL WizWP(OFFSET, 15, 2, 19, FILENAME(1), CommentId, HelpCol, BDCol)
   009 *
   010 READV NewText FROM INPUT.FVS 1) , CommentId , 5 ELSE NewText = ''
   011 DELETE INPUT.FVS(1) , CommentId
   012 GOSUB 35100
   013 INPUT.ITEMS 1)<15> = NewText
   014 IF NewText = OldText THEN DIRTY(1) = 1
   015 RETURN