CHAPTER 8. Creating Wizard Reports

About This Chapter
Turning Screens into Reports
Wizard Column Reports
   Creating a Simple Column Report
   Selecting screen fields to reuse
   Maximum length of a line
   Indenting a Detail Line
   Changing selected fields
   Changing the details of a selected field
   Changing a field justification
   Changing a field Label
   Changing a field Output Length
   Sorting by specified fields
   Ascending or descending sort
   Selecting by specified fields
   SELECT operators
   SELECT values
   Saving the Report Definition
Wizard Form Reports
   Page Headings and Footings
   Report Headings and Footings
   Break Headings and Footings
   The End of Report marker
   The @ commands, for special formatting
   Creating more elaborate reports
   How to delete a section marker
   Report Code Segments
      Common Time
      Entry Time
      After Read
      Exit Time
      User Defined
      Report Heading
      Report Footing
      Page Heading
      Page Footing
      Forms Detail
      Print Time
      Before Print
Wizard PROC Reports
   The Wizard PROCessor
   PROCESS Definitions
   Tilde Functions
      The Special Tilde Function
      Generic Tilde Functions
      GPAC Tilde Functions
      User Tilde Functions
How to use Wizard generated Reports

About This Chapter

In this chapter we will discuss the various methods of creating Wizard reports. There are three main types of reports that you may create with Wizard.

Instant Forms

This type of Report simply takes a Wizard Screen and turns it into a Report that you may send the output to the Screen, Slave or system Printer.

Columnar Reports

Simply fill in the blanks questions asked, to specify this type of Report. This type of Report may look as simple as an ACCESS type of report or you may have more than one line per item, to conserve space.

Forms Reports

These are special Reports such as Invoices or Purchase Orders etc. You create Forms type Reports by painting the Report in the same way that you would paint a Screen.

PROCessor Reports

ACCESS style reports allowing you to interactively prompt the data entry operator for data that can be validated, including pre and post processing or linking to other processes.

Turning Screens into Reports

The Instant form reports provides the simplest way to produce a report. The report you create using this procedure will be based on a data entry screen which you have already generated.

After you have created a forms-type report, you can customise your report with the Wizard Screens option from the W Menu.

When you select this option, you will be asked which data entry screen you want to reuse. Here you should type in the name of an existing data entry screen upon which you wish to base this report. The report, when it is created, will appear in a form that is virtually identical to this screen.

Once you have given the name of the data entry screen upon which you wish to base the report, you must then enter the name you wish to give the report. This is the name by which you may run the report.

The final step in generating the instant report is to answer Y to Wizard's question about whether you wish to generate this report. Note that you may answer N and, by using the Wizard Screen generator, make whatever adjustments to this report you wish, and then generate it.

Wizard Column Reports

Creating a Simple Column Report

To create an Instant Columnar Report, you select the fields to be printed on the report from a list of dictionary items. This makes it possible to design a columnar report in only a few minutes.

After you have created an instant columnar report you can customise your report with the Wizard Screens option on the W Menu.

Upon entering the Instant Columnar Report option, you are asked for the name of the file you wish to use. You respond by entering the name of an existing file.

Having entered the name of a valid file, Wizard will load the dictionaries from that file so that you can then construct the columnar report from them.

The next step in this process is to give Wizard the name the report. The name you give must be a unique name, not a name from any existing report or file, etc. The name you give will be used to run the report.

Note: Editing an Existing Columnar Report

If at this time, you attempt to enter the name of an existing columnar report, the name will be rejected, since it already exists. To edit an existing columnar report you should use the FS command from TCL or the Wizard Screens option on the W Menu.

Note that you do not need to generate a columnar report, it is sufficient to file it.

Selecting Screen Fields To Reuse

When you are building the Wizard Columnar Report, you will be asked to enter the number of the Field Definition that you want to reuse, N for the next detail line, D number to display, or OK if ok.

In response to this request by Wizard, you may enter:

1. The number of the field you want to display on the report. You can select the fields in any order (one at a time). Wizard will redisplay this message until you enter OK.
2. An N to tell Wizard to start the Next detail line. Wizard can produce a columnar report with more than one line on the report for each item (record) in the file. The idea is to select the fields (one at a time) that you want to print on one line and then enter an N if you want to use another line.
3. A D followed by a number to Display field definitions starting at that number. This command is only used if there are more field definitions than fit on the screen at one time.
4. OK to tell Wizard you are finished selecting fields.

Maximum length of a line

If you select a field which is too long to fit on the current detail line, Wizard will prompt you, asking you if you want to place this field on the next line or leave it out altogether. Valid responses are:

Indenting a Detail Line

Wizard asks you to enter the number of characters to indent the detail line.

Indenting a detail line also indents the corresponding line of the page heading.

One way to use this feature is to indent a 2nd detail line 5 to 10 characters, and then indent a 3rd detail line 10 to 15 characters. Indenting can make reports easier to read.

Changing selected fields

Wizard asks you to enter the number of the Field Definition that you want to change, Dnumber to display, or OK if ok.

You may respond by doing one of the following:

1. The number of the field you want to change. You can change any field that you selected to be in your report. Wizard will redisplay this message until you enter OK.
2. A D followed by a number to Display field definitions starting at that number. This command is only used if there are more field definitions than fit on the screen at one time.
3. OK to tell Wizard you are finished changing fields.

Changing the details of a selected field

Wizard prompts you by asking you to enter L to change the Label, J to change the Justification, O to change the Output Length, or <Return> to return.

In response you may enter one of the following:

1. L to tell Wizard that you want to change the field Label
2. J to tell Wizard that you want to change the field Justification.
3. O (the letter, not zero) to tell Wizard that you want to change the field Output Length.
4. <Return> to return to the select a field to change message.

Changing a field justification

Wizard asks you to enter a new Justification (L, R, or N). In response you enter one of the following:

1. L to tell Wizard you want to Left justify the data.
2. R to tell Wizard you want to Right justify the data.
3. N to tell Wizard Not to justify the data. The Output Length will be ignored. This will cause the data in this field to be printed next to the data from the previous field (with a one blank separation).
4. <Return> to leave the Justification unchanged.

Changing a field Label

If you want to change a field label, then Wizard asks you to enter a new label. You respond by typing either:

1. A new Label to replace the old Label. The new Label will now become part of the page heading The new Label can include any characters (upper or lower case) as well as leading, embedded, or trailing blanks. A new Label can change the length of a detail line if the new Label is longer or shorter than the old Label.
2. <Return> to leave the Label unchanged.

Changing a field Output Length

When changing the output length of a field, Wizard will ask you to enter a new output length for the field. You respond by entering either:

1. A new Output Length to replace the old Output Length
2. <Return> to leave the Output Length unchanged.

Sorting by specified fields

Wizard asks you to enter the number of the Field Definition that you want to sort by, or OK if otherwise.

1. The number of the field you want to sort by.
2. OK to tell Wizard you are finished specifying sort fields.

Ascending or descending sort

To specify the type of sort you want the instant columnar report to do, you may type either:

• A for an ascending sort for this field, or
• D for a descending sort for this field.

in response to the prompt by Wizard for the type of sort this field is to execute.

Selecting by specified fields

Selecting by specified fields is achieved by entering, in response to the prompt by Wizard asking you to enter the number of the Field Definition that you want to SELECT with, or OK if OK, one of the following:

1. The number of the field you want to SELECT with.
2. OK to tell Wizard you are finished specifying select fields.

SELECT operators

You may select any one of the following selection operators within the specification of selection criteria:

SELECT values

Wizard asks you to enter a value (such as a number or a date) to compare against the select field. You may enter a value, for example:

Saving the Report Definition

When you have finished defining your report, you will be asked whether you want to save the definition you have created. You have two options here, these being:

Once saved, the report can be run by typing its name from TCL or else from a menu once it has been installed in a menu.

Wizard Form Reports

You are probably familiar with Forms-Type Reports. Some examples of Forms-Type Reports that can be generated by Wizard are: Purchase orders, Cheques, Invoices, Statements, or even Form Letters.

There are two methods you may use to create a Forms-Type Report. For details on the first, refer to the first section in this chapter.

The second method of creating a Forms-Type Report is by using Wizard Screen Generator to create a Forms Detail Section, for example:

1. Select Wizard Screens from the W Menu.
2. Enter a Program Name, a Program Type of R, and the Main File Name.
3. Enter the (S)tart section command. You will be presented with the Report Section Menu.
4. Select the Forms Detail section. You will be returned to the Wizard formatting screen automatically. This screen will now display a Forms Detail section marker
5. Enter the (A)dd command. Position the cursor to the place on the screen where you want to display ORDER NUMBER.
6. Enter the data label Order Number.
7. Position the cursor to the place on the screen where you want to display the data for this field. In this case, place it next to the data label
8. Enter the Data type X, and the data length 8.
9. Continue this procedure until you have positioned and entered all the fields on the screen. The line-item set, LIS is entered with the (L)ine-item set command, with a depth of only 1.
10. If you want all of these fields to have the same Data Locations as fields in other programs, then you must use the (E)dit Command to specify Attribute Numbers for these fields. Otherwise, Wizard will assign unused Attribute Numbers to the fields. Also see the R Command.
11. Enter FI to save the work you have done, and generate the program.

Page Headings and Footings

If desired, you may add a Page Heading section to your report. The Page Heading will print at the top of each new page of the report.

If you want a Page Heading then select the Page Heading option from the Report Section Menu. The Page Heading marker will then appear on your formatting screen. It does not matter where you put the Page Heading section. Wizard will use it correctly. We suggest that you do put it in the correct place so that your documentation looks correct.

You may use the (A)dd command or the (T)ext command to enter field definitions or text into your heading. You may also use some of the special formatting @ commands which are also entered with the (T)ext command.

Page Footing Report Section

If you want a Page Footing then select the Page Footing option from the Report Section Menu. The Page Footing marker will then appear on your formatting screen. It does not matter where you put the Page Footing section Wizard will use it correctly.

You may use the (A)dd command or the (T)ext command to enter field definitions or text into your footing. You may also use some of the special formatting @ commands, which are also entered with the (T)ext command.

Report Headings and Footings

The Wizard report generator allows you to print a Report Header of any length (number of lines) you desire. The Report Header may consist of text, field definitions and the special formatting @ commands

To use a Report Header in your report you select the Report Header option from the Report Section Menu. The Report Header may be placed anywhere on the formatting screen.

If you want the Report Header to be on a page separate from the body of the report, then end the Report Header with the special formatting @ command for form-feed: @FF.

If you also have included a Page Header in your format, the Page Header will be printed at the top of every page including the page with the Report Header.

The Report Footing Section

If a portion of a report contains Break sub-totals then it is generally desirable to print a grand-total at the bottom of a report. The Report Footing section accommodates the printing of grand-totals, as well as any other data or text that may be desired at the end of the report.

At this point, you would typically use the (C)opy command to copy one or more fields from the detail section to the report footing section.

For the following example, you could copy the SALES field from the Columnar Detail section to the Report Footing section. You might also want to add some text, and/or change the data labels.

Break Headings and Footings

You may want to print sub-totals on your Report. This is done by designating one or more data fields of the detail section to be Break control fields. A Break occurs whenever the data for a Break control field changes. At each change, the sub-totals will be printed for the data since the previous change. This data is called a Break group.

To define a Break control field, use the (S)tart section command. When presented with the Report Section Menu, select the BREAK FOOTING option.

Wizard will ask you for the Field Name of the Break Footing control field. You will enter one of the Field Names from the COLUMNAR DETAIL SECTION. Wizard will display a list of the Field Names at the top of the Screen.

At this point, you would typically use the (C)opy command to copy one or more fields from the DETAIL section to the Break Footing section

As an example, you could copy the REGION and SALES fields from the Columnar Detail section to the Break Footing section. You might also want to add some text, and/or change the data labels.

Multiple Break Footings

You may add as many Break Footing sections as your Report requires. However, multiple Break Footings require a definite order.

Important rule: The rule is that the Break Footing control field names must be ordered on the screen from the highest priority to the lowest priority.

In the above copy example, Region has the highest priority, since there are many States in a Region. States are the next highest priority, since there are many Cities in a State.

It is not necessary for Break Footings to be contiguous, only that they be ordered from highest priority to lowest priority.

Break Heading Report Sections

You may find it desirable to specify a Break Heading to describe, with text and/or data, some information about the data that will be grouped together due to the break footings

Break Headings do not have to be ordered, and they may be placed anywhere on the screen. Wizard knows where to put the Break Heading section when it generates the Report program.

NOTE: a Wizard report can contain a break footing without a break heading, but a break heading must have a corresponding break footing.

The End of Report marker

The End of Report marker is used to add blank lines to the last report section on the formatting screen. (except the columnar detail section which ignores all blank lines).

Position the Cursor one or more blank lines beneath the last line you have formatted. Then enter the (S)tart section command, and select the End of Report marker option. The blank lines will be printed as blank lines on your report.

The @ commands, for special formatting

A selection of special formatting commands are available to you when building your reports. Actually, these commands are text strings that are entered with the (T)ext command. However, it is appropriate to discuss them here.

@FF Command

@FF Tells Wizard to print a Form Feed character to the output device. This causes the printing on the present page to end immediately, and begin printing on the next page. The @FF command must be placed on a line by itself starting in column 1.

@PG Command

@PG Tells Wizard to print the sequential page number, left justified in a field of four spaces. The first digit will appear exactly where the @ character is placed.

@DATE Command

@DATE Tells Wizard to print the present system date in the form of 10 JAN 1984. The date is printed left justified in a field of 11 spaces. The first digit will appear exactly where the @ character is placed.

@TIMEDATE Command

@TIMEDATE Tells Wizard to print the present system time and date in the form of 11:22:33 10 JAN 1984. The time and date are printed left justified in a field of 21 spaces. The first digit will appear exactly where the @ character is placed.

@EXP Command

@EXP Tells Wizard to commence printing in expanded print. The @EXP command must be placed on a line by itself starting in column 1. All subsequent lines will be printed in expanded print until Wizard encounters the @DEXP command

@DEXP Command

@DEXP Tells Wizard to stop printing in expanded print and print all subsequent lines in normal print. The @DEXP command must be placed on a line by itself starting in column 1.

@HEADING Command

@HEADING Tells Wizard to get the Account Title.

Technical Note

All these @ commands are items in the WDATATYPES file. The parameters in these items are used when the report is generated. You may find it useful to (very carefully) modify these parameters to suit your own requirements. Examine the parameters to figure out what they mean.

Also, you can create your own @ commands by creating new items (that start with the character @) in the WDATATYPES file, use the maintenance Screen provided.

Creating more elaborate reports

It is possible to use Wizard Screen Generator to create Columnar reports which contain multi-line page headings and multi-line detail.

To create such reports, first you select the Columnar detail section from the Report Section menu. Then use the (A)dd command to define the data fields and their labels.

How to delete a section marker

If you find it necessary to delete a Section marker, follow these steps:

1. Enter the (S)tart section command.
2. Place the Cursor on top of any portion of the Section marker to be deleted.
3. Select the Delete Section marker option from the Report Section Menu.

Wizard will then delete the Section marker and return to the formatting screen. If you have previously entered data fields or text into the section, you may also want to delete the fields or text.

Remember, fields are deleted with the D command and text is deleted with the T command

Report Code Segments

Common Time

The Common Time CS for reports is identical to that for screens.

Entry Time

The Entry Time CS for reports is identical to that for screens.

After Read

After Read is a Global Code Segment and can only be used in Wizard Reports.

It is executed every time Wizard Reads the Major file. This is exactly the same as Old Item Time. Wizard Reports do not write any records to the Major or Linked files.

This is a good place to check if the Item has already been printed; in the case of Invoices for example, if it has been printed already then either reject it or set a field to "Re-Print". It is also the place to write flags on the Major Item; indicating that it has been printed.

After Read is After :

Wizard reads each of the Major Items.

After Read is Before:

Wizard assigns the Field Names ready for Printing.

Exit Time

The Exit Time CS for reports is identical to that for screens.

User Defined

The User Defined CS for reports is identical to that for screens.

Report Heading

Report Heading is a Global Code Segment and can only be used in Wizard Reports

It is executed only once at the beginning of Wizard Reports, this is a good place to suppress the Report Heading.

Report Heading is After :

After Read for the first Item only.

Report Footing is Before:

Wizard prints the Page Heading for the first Page.

Report Footing

Report Footing is a Global Code Segment and can only be used in Wizard Reports.

It is executed only once at the end of Wizard Reports, This is a good place to suppress the Report Footing.

Report Footing is After :

Page Footing for the last page of the report.

Report Footing is Before:

Wizard exits the report.

Page Heading

Page Heading is a Global Code Segment and can only be used in Wizard Reports.

It is executed at the beginning of every page in a Wizard Report. This is a good place to suppress the Page Heading.

Page Heading is After :

The PRINT.HEADING variable has been set to 1; this is checked before Wizard prints any line.

The PRINT.HEADING variable is set to 1 before Entry Time and after Page Footing.

Page Heading is Before:

Wizard prints any line and the PRINT.HEADING variable is set to 1.

Page Footing

Page Footing is a Global Code Segment and can only be used in Wizard Reports.

It is executed at the end of every page of a Wizard Report This is a good place to suppress the Page Footing.

Forms Detail

Forms Detail is a Global Code Segment and can only be used in Wizard Reports.

It is executed for every line when printing the detail section within Wizard Reports, this is a good place to suppress the Forms Detail for a given multi-value or sub-multi-value.

Forms Detail is After :

Every other time except Report Footing and Exit time

Forms Detail is Before:

Wizard prints any line within the Detail Section.

Print Time

Print Time is a Global Code Segment and can only be used in Wizard Reports

It is executed every time any line is printed, this is a good place to suppress a given line.

Print Time is After :

Has loaded the P$ variable and is about to print it.

Print Time is Before:

Wizard prints any line from any Section.

Before Print

Before Print is a Field Code Segment and can only be used in Wizard Reports.

It is executed Before Printing a given Field and it is much the same as Before Field in a Wizard Screen. This is a good place to SKIP the current Field. Note: Before Print will affect the entire line that the Field is on; if you skip it.

Wizard will execute this Code Segment twice; Before it prints anything for this Report Section and after it has finished printing for this Section.

The variable BEFORE.PRINT is set to 1 the first time and is set to 0 the second time. Your code must look at this variable or it will be executed twice. For example:

   IF BEFORE.PRINT THEN
      {Your Code for this Section before printing}
   END ELSE
      {Your Code for this Section after printing}
   END

Before Print is After :

Wizard loads the variables for the given line that the given Field is on.

Before Print is Before:

Wizard loads the P$ variable prior to printing it for the given line that the given Field is on.

Wizard PROC Reports

The Wizard PROCessor

The Pick PROC language is the most efficient way of processing ACCESS (also called English, Inform, or Recall) sentences and any series of Jobs, whether they be Basic Programs, Verbs or sentences.

That being said there are many problems associated with Procs. As one's skill increases these problems reduce but are never removed. Importantly as we solve the problems, the Proc becomes less and less efficient at run time and increasingly difficult to understand and maintain.

Some of the problems with Procs are:

• Hard for users to understand and modify
• Hard to document - impossible to automatically document
• Difficult to prompt for user input, particularly multiple input for one question, e.g.

     ... WITH CUSTOMER.NUMBER = "123""456"...
  

  or multiple questions (if answer one was null, is the answer to the second question in buffer 1 or 2?)

• What are buffers anyway?
• Hard to provide online help
• Hard to validate user entries (try validating a date or if an entry is an amount of money between $3.00 and $5.00, or if the entry is an ID on the customer file.)
• Hard to allow the user to confirm valid entries, (display the customer's name in response to a entry of a customer ID)
• Hard to include or not include AND or OR if the user bypasses a selection.
• Hard to make SAVE-LISTs unique to a port number to allow concurrent processing of the same process.
• Hard to make dictionary item definitions dynamic (use BAL3 if operator requests period 3)
• Hard to determine the width of the resulting output, particularly when dictionary items output widths change (from altering the column heading or the output width specification).
• If the stack is on, the Access sentence must be broken into pieces less than 140 characters and except for the last piece, followed by <<, (what is the stack anyway?)
• Hard to allow users to perform their own TCL commands during data entry to assist them in determining appropriate answers. If TCL use is granted, what about security?

Competent Proc writers have technical answers to most of these questions. They involve user-exists, basic programs, Proc-Read and Proc-Writes and buffer clearing. But how competent does a user have to be to maintain and modify the result?

One solution is to write Basic programs that execute a Sentence. This has some limitations but, most importantly, how does a user maintain them? Not only does a user need to know Access and Editor, they also have to understand Pick Basic. Does a user need all these skills to add STATE to the Customer List? Do we want all users to have editor privileges on Basic source files just to do this sort of change?

Some people never master Procs and now they do not have to. The Wizard PROCessor writes fully featured, working and efficient Procs. The process is easily understood and no knowledge of Proc is required. Correct, meaningful and up-to-date documentation is automatically produced.

In addition, the Wizard PROCessor gives a compatible platform for systems that do not support Proc, eg. Unidata, or do not run them very efficiently, eg., Information and PI Open.

PROCESS Definitions

Menu Definition

The recommended technique for commencing all applications is to construct the menus and use the Menu System facilities then build the individual components.

To specify an item from a menu as a Wizard PROCessor routine, the type should be R (R for Report). Refer to the manual section on maintaining menus for more information.

PROCESS Definition

Wizard PROCessor items are maintained via a system Wizard screen (called W.ENTER.REPORTS). You can get to this screen from the report menu in the W (Wizard screen generator menu. Alternatively, as recommended above, you can create or maintain a Process Definition which is already installed in a menu by moving the Menu highlight bar onto the item and typing ED followed by <Return>. (Note that to do this you must have security clearance. Refer to the section in the manual on setting up users.)

If multiple Process definitions are linked together, after filing, (not Escaping from), one definition, the next will be fed to the maintenance program.

Some knowledge of ACCESS is mandatory. No knowledge of PROC is required. Online help is available including Dictionary lists.

The next release of Wizard PROCessor will substantially reduce the amount of ACCESS knowledge required.

Process Definition Structure

A Process Definition is broken up into a number of logical components. This is done to provide the optimum in facilities. The structure may be bypassed and while the result may work, benefits will be lost. The structure is simple, logical and meaningful, please follow it.

The basic structure is:

• Verb/File/Sort Keys
• Imbedded Selection Criteria
• Nominated Selection Criteria
• Output Specifications
• Output Device Specification
• GET-LIST and SAVE-LIST nomination
• Linked Processes

All components are optional but certain associations must be made, for example, Output Specifications are useless without a Verb or File.

Detail of Process Definitions

Note 1.

The first field Report Name has a standard Wizard Look-up by field 1 Description, therefore you may enter = and follow the instructions, or enter ={one word of the Description}, or part of the word by [].

Note 2.

Reference will be made to Tilde ~ functions. Tilde Functions are special items that change at run-time. They provide much of the Power of the Wizard PROCessor.

Note 3.

Entry of the <Control> and R key (R for Release Margin) key can be used on all fields to enter data longer than the screen display length.

Note 4.

Most fields allow multiple lines to be entered, entry of the /W command will open a window allowing you to enter multiple lines of data.

Note 5.

The Wizard = (Look-up command may be used on fields that require DICTionaries, the Look-up lists the valid DICTionary of the current file. If no file has been specified, the user is prompted for a file-name. The Look-up is a Wizard Multi-Select Look-up which allows you to select more than one DICTionary item and your selections may be in any order. The DICTionary items which you select will be returned to the given field in the order in which you selected them.

The Following pages show the Wizard Screen ENTER.REPORTS, this screen is used to maintain PROCess Definitions.

Tilde Functions

The Special Tilde Function

Tilde functions fall into these groups:

• Generic
• GPACs application specific (GPAC is a one off suite of business applications developed in Wizard 4GL), and
• User defined

All valid tilde functions are replaced at runtime by their appropriate, then current, values.

How do Tilde functions work?

Tilde functions only require Wizard's Menus and the Wizard PROCessor.

The rules are few and simple. The explanation seems a little harder at first, please keep reading. When you understand, your power will be increased many times over.

A simple example is to show who a report is for:

Include in the Heading:

   this report is for ~WHO

At runtime, the user's name will be included in the heading, for example:

   This report is for John

You may use tilde functions almost anywhere, the description on each will show by definition where they can and cannot go. For example ~PORT can go anywhere at any time as the Port is a constant, however ~I is only valid after operator Input.

If you wish a tilde function to be concatenated to text or another tilde function; entry is:

   MY.LIST~PORT

or

   ~PORT~WHO

If on the other hand you wish to concatenate text to a tilde function then you must use the pipe (vertical bar) "|" key; entry is:

   ~PORT|MY.LIST

Generic Tilde Functions

The Generic functions only require the Wizard Menu System and the Wizard WizPROCessor.

Generic tilde functions are as follows:

~WHO

~WHO give the user name, eg. JOHN. It does not include the port number.

~PORT

~PORT gives the user port number. The port number is without leading zeros. Eg. 1, not 01.

~An

~An returns the nth entry passed by the menu system. Note there is a maximum of 9 available.

Refer to the section on Menu Maintenance for information on how to implement this powerful feature. Its main function is to allow the process to adapt itself to the particular situation.

Here is an example:

A menu is setup with two options, "Current Enquiry" and "History Enquiry". Both options use the same process but pass to it a different parameter say "CURRENT" and "HISTORY".

The process could then say:

   SORT ~A1.FILE

In one case this would produce:

   SORT CURRENT.FILE

and the other

   SORT HISTORY.FILE

~ID

~ID returns the ID of the current Proc Definition. This is useful in headings, particularly the standard heading definition.

~DESC

~DESC returns the first line of the multi-line Description of the current Process Definition. This is useful in headings, particularly the standard heading definition.

~I

The ~I function has a number of forms, ~I, ~In, Inn, ~Inn,nn or ~Inn.

The ~I function has two steps.

• It may be used to prompt and direct user input into the input stack which is subsequently used in the second phase.

  ~I or ~Inn input requests are entered in the User Selection Section. The ~I or ~Inn is put in the dual purpose With/And/Or column.

  Note: ~I in this column will work the same as INPUT in this column.

• The second phase is to substitute users responses into the generated Process. The user responses can be from User Requested Selection Criteria and/or from INPUT and/or ID and/or ~I requests. They all go into the same input stack.

  Even though Verb/File/Sort Keys and Imbedded Selection Criteria sections are defined before the Selection Criteria Requested from User, they are processed after it. Therefore user responses are available to those sections.

  ~I functions are particularly useful for Selection definitions where user input is also required by a Linked program.

  For example, Bank Code may not be part of a selection process to select data for a cheque printing process, but it is required by the print program. Rather than ask the user for selection criteria, then do what may be a lengthy selection process, then ask for Bank Code, it is best to ask for, and validate, all answers up front, and pass the necessary response to the Linked program. Similarly, Due Date may be required by the Selection process and by the Linked Program.

  In this example the User Selection Section could look like this:

  With/and/or	Dictionary	User Prompt
  INPUT		Bank Code
  AND WITH	DUE.DATE	Due Date

  and the Linked Process could be:

     PRINT.CHEQUES ~I2 ~I1
  

  the PRINT.CHEQUES program inputs the Due Date and then the Bank Code.

  All user entries in response to the User Selection criteria, except for null responses, are stored in the Input Stack. The sequence is simple, the first entry is position one, the second entry is position two, and so on.

  Important Note: This includes multiple response to one item where permitted.

  If for example the first User Selection was for Optional, Multiple Supplier ID's, the position in the Input Stack of subsequent response would be unclear at the time of creating the Process Definition.

  For example, if the second User Selection was for Bank code, and if no Creditors numbers were entered, then Bank Code would be I1. If one Supplier ID was entered, then Bank Code would be I2. If three were entered, I4 and so on.

  To ensure the position of a required parameter, specify it before optional and multiple User Selections.

  Or reference the Input stack as "~Inn,nn". When you use the comma (,) the Wizard PROCessor will reference the ~I{prompt number}, {multi-input number}. The {multi-input number} is optional.

  That is in the above example the Bank Code would always be in ~I2,, regardless of the number of Supplier IDs or even if there was no Supplier IDs entered.

  Note: You could reference the third Supplier IDs by ~I1,3; there may not be a third one.

  When specifying the input of a ~I function it may have an optional one or two digit number following it. eg. ~I3 or ~I13. This will store the response (user input) in the nominated position in the Input Stack.

  Warning: If you specify a low number, and one of the previous requests allows multiple responses, the data in this low number could be over written.

  Also where the stack position is nominated, the counter is not increased. Having said that, you may still reference particular items in the input stack by the ~Inn,nn. The positions of these do not change even with Multiple, Optional entries.

How do you use the ~I functions?

Specifying where ~In values are to be inserted is quite simple. The position n must be specified (if not position 1 is assumed).

They may even be used in the User Selection Section itself. The particular stack entry must already have been loaded by a previously defined User Selection line or the stack position will be null.

~HDD

The Wizard Menu System uses an item with an ID of HDD in the file WIZ.CONSTANTS. The ID HDD is used for historical reasons, it means Heading Detail. Attribute two of the item contains the Logo text to be displayed after logon when the operator ID is being requested.

Attribute one of the item may contain a general user name, typically the Organisation name, for inclusion in report headings, documentation, etc.

This text may be called up with the ~HDD function.

For example, a Heading containing:

   Balance Sheet for ~HDD

would at runtime read:

   Balance Sheet for Mega Corp Inc.

~CR

This is to be used to pass a null <Return> to a Linked Process, or to the Verb. A ~CR is only valid in a "Linked Process" line.

~Dnn or ~Dnn,nn

The ~D function is used to access the data in the Display fields. Whenever you have an Input you may also have a Display. ~D functions work the same way as the ~I function, in fact they get their position in the Display Stack from the Input Stack.

That is it follows all of the rules relating to where the Display data is going to go and subsequently where it comes from, and how and when you can use them.

As an example, let us say that you want a report showing all of the un-processed Sales Orders for a given Customer. Your User Selection Section could ask for the Customers Id., this would be validated against the CUSTOMER file and the Display would be the Customer's Name. The Customer's Name will go into the Display Stack at the same location as the Customer's Id would go into the Input Stack. Lets say the nn=1 and the entry was "BOB1".

The Verb/File/Sort Keys would be:

   SORT SALES.ORDERS BY DATE.ORDERED

The Imbedded Selection Criteria of the PROC would be:

   WITHOUT PROCESS.FLAG

The Heading would be:

   <~ID>   Un-Processed Sales Orders for Customer ~D1

This would give the following:

   SORT SALES.ORDERS BY DATE.ORDERED WITHOUT PROCESS.FLAG
   WITH CUSTOMER.ID = "BOB11" {your Output DICTionaries}
   HEADING "<ProcId>  Un-Processed Sales Orders for
   Customer Robert J. Guthrie"

~READ

The ~READ function is a very powerful function and can be used in most places. Most of the time it would be used in the Heading, Footing or for passing data to Linked Process.

Think before you use this function as it may be easier to use a ~D instead of a ~READ. The following will show how to specify a ~READ:

• ~READ;{File};{Id};{amc};{vmc};{svmc};{Opt}
• {File}

  The file to read. Also {DICT_File}, if using a DICTionary file you MUST use the _ character.

• {Id}

  The Item Id to be read.

• {amc}

  The attribute number. Default is zero. ie. The entire Item.

• {vmc}

  The Multi-Value Default is zero. ie. The entire attribute.

• {svmc}

  The Sub Multi-Value Default is zero. ie. All of the Values

• {Opt}

  The Options. See below.

All of the above may be any valid ~ function including a ~READ, (ie. the result of ~READ can form part of the specification of another ~READ).

The Options are as follows:

C	Return the Id if the Item is not on the given file. If the data in the specified location is null then a null is returned.
V	Validate that the Item is on file and that the value obtained is not null.
X	Return null if the Item is not on file or if the value is null.

To each of the above Options you may Prefix the letter T for Total. If you wish to use the total option a few rules apply:

• If the {amc} = 0 then the attributes are totalled.
• If the {vmc} = 0 then the multi-values for the given attribute are totalled.
• If the {vmc} > 0 then the Sub-multi-values are totalled for the given attribute and the given multi-value.
• When adding up the values, if any value is not numeric then this will cause an error.

Special Note about ~READs:-

All components of the ~READ must be valid. That is the {file} must be a valid file; the {amc}, {vmc}, and {svmc} must be numeric (null is Okay); the Options must be valid. If the Option is V then the {Id} must also be valid. If the Option is Prefixed with the letter T for TOTAL then each of the values must be numeric. If any of the above are invalid then an error will occur.

If you get an error with the ~READ function then the process will exit back to the Menu as if the operator hit the <Esc> key.

The following is valid :

   ~READ;{file};{Id}

the following defaults would apply:

   {amc}=0; {vmc}=0; {svmc}=0; {Opt}=X

~OPER

The ~OPER is the Operator Id entered when logging into the current account.

For example ~OPER = "JOHN" (In most cases this is the same as ~WHO).

~ACCOUNT

This is the actual PICK account name. It may be the same as the ~WHO but if you have executed the CHARGE-TO then ~WHO would be "SALES*JOHN" and ~ACCOUNT would be "SALES"

~DEVICE

This function returns the Operators Device Choice. If the Operator is not given a choice then this is the Default Device. ~DEVICE has been provided to allow you to pass the Operators Device Choice in the Linked Process. This could be for a "B"efore Linked Process to assign the correct Printer.

For Example:

You may have various Reports; based on the Report ~ID and/or the ~OPERator and you wish to control as to which Printer the given Report is to go to. You would have a program to look at all these values and work out the correct Printer assignment, therefore the Linked details could be:

Linked Process	Type
SP.CONT ~DEVICE ~ID ~OPER	BV

SP.CONT would first check ~DEVICE if it is "P" then check the Report ~ID and ~OPERator to then EXECUTE the correct SP-ASSIGNment.

   SUBROUTINE MENU.REP.SUB.NAMES( NAME, AUTO.FLAG, HEAD.FLAG)
      * Test MENU.REP user defined subroutine
      BEGIN CASE
         CASE NAME = `JIM`
            NAME = 'Jim Spriggs'
         CASE NAME = 'NEDDY'
            NAME = 'Neddy Seagoon'
      END CASE
   RETURN
   END

   Return executed with no gosub

   Browsing Commands are: PR PL T B G RETURN / ?