Code Segments are used to handle Wizard program requirements that are not handled by the standard Wizard features. Each Code Segment may contain standard BASIC statements as well as special Wizard language statements.
Code Segments are added to a Wizard program definition by using the EC Command. When the program is generated, the Code Segments are automatically added to the program as internal (GOSUB) subroutines. Each Code Segment is executed at a particular time during the running of a Wizard program (depending on the Code Segment Type).
Since the Code Segments are internal subroutines, they can access all the variables used in the generated program. This allows tremendous flexibility as well as fast (run-time) speed. Some knowledge of BASIC is necessary to use the Code Segment feature.
The Code Segment feature makes it possible for the application designer to create complete, efficient applications with a minimum amount of programming.
There are sixteen (16) Code Segments. That is, they are related to the entire Wizard program being created. There are five Field Code Segment and these are related to each individual Field Definition and they are called Field Related. The other eleven are Global Code Segment types.
For each Wizard Screen or Report program, you may use one of each of the Global Code Segments. For each Field Definition within the Wizard program, you may use one of each of the Field Code Segments.
Note not all Code Segments are the same in Wizard Reports.
Wizard provides several commands which allow you to maintain code segments. These all operate from the main command prompt of the Screen Formatter They are:
| EC | Edit code for a field, both Global and Field Code Segments. If the command is not followed by a field number, you will be asked to move the cursor to the field whose code you wish to edit. (Full Screen) |
| ECG | Edit the Global Code Segments. (Opens a Window) |
| ECF | Edit the Field Code Segments, works the same as the EC command (Opens a Window) |
| EBI | Displays the first line of all Before Field code segments for the screen and allows you to edit them. (Opens a Window) |
| EIC | Displays all Input Conversion code segments. (Opens a Window) |
| EOC | Displays all Output Conversion code segments. (Opens a Window) |
| EAI | Displays all After Input code segments. (Opens a Window) |
| EAF | Displays all After Field code segments. (Opens a Window) |
All these options allow you to edit the code by selecting the appropriate line number.
When painting a Wizard data entry Screen the EC Command will show the following Screen:
When painting a Wizard Report the EC Command will show the following Screen:
Common Time is a Global Code Segment and can be used in both Wizard Screens and Reports.
Sometimes you may want to share data between programs without having to write the data and then read it in the next program, or without having to pass it as a parameter to a subroutine (which takes more memory). This may often be achieved by using the BASIC COMMON statement. (For more information on the way COMMON works, refer to your system's BASIC manual.)
Common time is executed immediately after the Wizard common and is the first Code Segment in the Wizard screen Although you may put code here, you would usually only want to put common statements in here.
Note that no Wizard variables have been assigned at this time.
Entry Time is a Global Code Segment and can be used in Wizard Screens or Reports.
It is executed only once after a Wizard program is entered (starts running). All Wizard Screen variables have been assigned, files opened and the Screen has not been painted as yet.
This is the place that you could do your own user Security checks or read control type records and/or setting default variables.
It is possible to reprogram the function keys for specific Wizard screens. A good place to do this is in the Entry Time Code Segment. Wizard will have already read the default definitions for function keys into a dimensioned array named func(). This array has 24 elements, 1-12 for the unshifted function keys, and 13-24 for the shifted function keys.
The following sample code will set function key 3 to enter the string "//CUST" which would cause the Jump-time command "//CUST" to be executed when
001: func(3) = "//CUST"
New Item is a Global Code Segment and can only be used in Wizard Screens
When a Wizard Screen is running, the data entry operator will enter an item-id to select an item. Wizard then determines if the item is an old item (already exists), or a new item (does not exist yet).
If the item is a new item, then the Wizard variable NEWITEMFLAG is set to 1 and then the New Item Code Segment is executed.
This is a good place to set default values for fields.
Command Time Code.
Input Conversion Time Code.
Wizard reads from the Major File and finds that this is a New Item.
After Input Time Code.
Old Item is a Global Code Segment and can only be used in Wizard Screens
When a Wizard Screen is running, the data entry operator will enter an item-id to select the next item. Wizard then determines if the item is an old item (already exists), or a new item (does not exist yet). If the item is an old item, then the Wizard variable NEWITEMFLAG is set to 0 and then the Old Item Code Segment is executed.
This is a good place to check if the Item is valid or not.
When a Wizard screen encounters a new item, the program prompts the user for each of the fields on the screen. If it is an old item, Wizard displays the item and moves input to the Acceptance Prompt. If you want to force Wizard to move through the fields of an old item you simply fool Wizard into thinking that the item is a new item with the code:
NEWITEMFLAG=1
In the Old Item code segment.
Command Time Code.
Input Conversion Time Code.
Wizard reads from the Major File and finds that this is an Old Item.
Output Conversion Time Code.
After Input Time Code.
Command Time is a Global Code Segment and can only be used in Wizard Screens.
The Command Time Code Segment is executed immediately after any input is entered at any Wizard Screen field.
This is a good place to intercept Wizard Commands and/or create your own Commands.
Input Conversion Time Code.
The Acceptance Prompt is a Global Code Segment and can only be used in Wizard Screens.
It is executed immediately after the data entry operator enters data at the Acceptance Prompt
This is similar to Command Time.
File Time Code, if the user just hit the enter key.
Delete Time Code, if the user entered the Delete command FD.
File Time is a Global Code Segment and can only be used in Wizard Screens.
In a Wizard Screen the File Time Code Segment is executed immediately before the Wizard Screen files the Main or Major and any Linked items that have changed.
This is a good place to check the integrity of the Items about to be filed or to update any control records.
Wizard checks that there is data in all of the Mandatory fields
Delete Time is a Global Code Segment and can only be used in Wizard Screens
The delete time Code Segment is executed just after the data entry operator enters an FD command at the Acceptance Prompt, and just before the data item is deleted.
This is a good place to check if the given user is allowed to delete the current item and/or update control records.
Acceptance Prompt Code.
Wizard will not delete Linked items!
Exit Time is a Global Code Segment and can be used in both Wizard Screens or Reports.
In a Wizard Screen or Report, the Exit Time Code Segment is executed only once, immediately before the Wizard program is exited.
This is a good place to handle processing that needs to be done just once when a Wizard program is exited. For example, saving "batch totals".
File or Delete time if the Wizard variable ID.SOURCE is set to 2.
The user enters
User Defined is a Global Code Segment and can be used in both Wizard Screens or Reports.
Unlike the other Code Segments the User Defined Code Segment is not automatically executed and is a good place to put Code which is required more than once, or code that is more than 5 to 10 lines long.
Instead, you use it to hold one or more local subroutines (the object of a GOSUB statement). These local subroutines are executed by the use of GOSUB statements in other Code Segments.
To prevent statement number conflicts within the Wizard generated program, you can use only numeric labels from 101 to 299 or 1000000 to 2999999. You may also use any alphanumeric labels.
Display Time is a Global Code Segment and can only be used in Wizard Screens
When a Wizard screen is generated it automatically paints the screen for you. Sometimes, however, you may wish to add your own display "hacks" to the screen. This can be done using the Display Time code segment. This code segment is executed each time the screen is refreshed prior to the painting of the fields. (This way, if you have inadvertently displayed something where some of the data for the screen appears, that data will display as a priority.)
The Screen has been Painted and the Wizard variable BEFORE.PRINT is set to 0.
Before Field is a Field Code Segment and can only be used in Wizard Screens.
You can have one Before Field Code Segment for each Field. It is executed just before the data entry operator is prompted for input. This a good place to Skip the current Field.
User input for a given Field.
Input Conversion is a Field Code Segment and is only used in Wizard Screens.
Each Wizard field can have an Input Conversion code segment Typically, you would use an Input Conversion code segment to validate the user's data input into a field. This code segment is executed after Wizard has executed its own input validation.
Command Time Code.
Wizard's input conversions.
Output Conversion Code.
After Input Code.
Output Conversion is a Field Code Segment and is only used in Wizard Screens.
Each field on a Wizard screen may have an Output Conversion code segment The Output Conversion code should generally be used to convert data from an internal format (i.e., how it is to be stored on the file) to the format in which it shall be displayed. In this respect it is the reverse of the Input Conversion
Data for a field is printed on the Screen.
The data for the current Field is Printed on the Screen. Therefore, it is also before Before Input, as the data about to be prompted for is printed on the Screen.
After Input is a Field Code Segment and is only used in Wizard Screens It is executed immediately after the data value for the field is displayed and is executed only if data is entered into the Wizard field by the data entry operator. This is a good place to check whether or not you need to Skip subsequent Fields.
The data is printed on the Screen.
After Field is a Field Code Segment and can only be used in Wizard Screens It is executed immediately after the After Input Code Segment and it is executed whether the operator enters data or simply presses the
After the operator presses the
It is important to know the Sequence of Operation of a Wizard data entry program in order to decide which kind of code segment should be used for a particular task, and to debug a code segment if it is not doing what you want. A Code Segment is a section of the Screen Code that Wizard will GOSUB to, only if you have placed Basic Code in the given Segment.
The Sequence of Operation is as follows:
| 200000 | Entry Time CS |
| 100000 | The data labels and text fields are printed on the screen. |
| 220000 | Display Time CS |
| 2000 | Input Processing Loop for each field. |
| 380000 | Default specification. |
| 400000 | Before Fields CS |
| If FIELDMODE = D (Display Only), then no more processing is done for this field, RETURN from subroutine 2000. | |
| If FIELDMODE = I (Input Once) and data existed in the field then no more processing, RETURN from subroutine 2000. | |
| WInput | Operator prompted for input, stored in I$ and WCOM. |
| 800000 | Command Time CS |
| 2100 | If a command has been entered, the command is executed. |
| If the data entered is a | |
| 2020 | The Mandatory specification is checked. If this field is a mandatory and there is no data already in this field then, the operator is prompted again for data entry. |
| The Skip if no data specification is checked and SKIPNUM is reset, no more processing for the field is done. | |
| If a data value has been entered, then: | |
| 2500 | The validation specification is performed on the data entered. |
| 450000 | Input Conversion CS |
| 50000 | If this field is an Item-id field, then the data value is used as an Item-id to read the Item from the file. |
| 250000 | If the Item does not exist, the New Item CS is executed. |
| 260000 | If the Item exists, the Old Item CS is executed. |
| The Item-id is stored in the array INPUT.IDS(ITEMNUM). | |
| If the data value is not an Item-id, then the data value is stored in the array INPUT.ITEMS(ITEMNUM). ITEMNUM contains the item number of the current Wizard field. | |
| 37000 38000 38100 | One or more data values are redisplayed on the screen, depending on what was just entered. |
| 550000 | During the display of data values, the Output Conversion CS is executed once just before each data value is displayed. Calculation specifications, if they exist, are executed at the beginning of the Output Conversion CS. |
| 500000 | After Input CS |
| 600000 | After Field CS. This code segment is not executed if a command is entered that begins with / or ?. |
| The variable CF is incremented by the variable SKIPNUM to determine the next field to be processed. SKIPNUM is usually set to 1. | |
| Processing begins on the next field until all fields are done. | |
| 2200 | Acceptance Prompt |
| The Acceptance Prompt message is displayed. | |
| 14000 | File the item: Wizard will check all Mandatory fields to see that they contain data. |
| 900000 | File Time CS |
| 15000 | Delete the item |
| 950000 | Exit Time CS |
The User Defined code segment is comprised of one or more local subroutines, each of which you will label with a statement number. The statement number is selected by the designer. The User Defined routines are executed only from other code segments They are executed as the result of a GOSUB statement from a given code segment.
Only some types of Code Segments may be used in Wizard Reports and the Code Segments are executed only if they exist.
The Before Print CS (equivalent to Before Field in Wizard Screens), is executed just before the specified Wizard field is printed.
Wizard language statements are an extension of PICK/BASIC.
Important Note: All Wizard language statements must begin with a # (number sign, sometimes called pound or hash) in the first column of the code line.
If EXTENSION, UNITCOST, and QUANTITY are fieldnames in a Screen or Report then the following Code Segment:
# EXTENSION = UNITCOST * QUANTITY
will multiply the current contents of the UNITCOST field by the current contents of the QUANTITY field and store the result in the EXTENSION field.
The following Code Segment:
# DISPLAY EXTENSION
will update the display of the field called EXTENSION.
The following Code Segment:
# CHECK.TOTAL = TOTAL(CHECK.DEBIT.V)
will sum the values of the multi-value field CHECK.DEBIT.V and store the result in the CHECK.TOTAL field. Note that most totals are done as a Derived Calculation by using the E Command.
When writing Code Segments, you will probably want to access some of the variables that are used in a Wizard program We have included here the variables that are most commonly used in Code Segments. Most of these variables are used in the Code Segment examples that follow.
You can learn more about the Wizard variables by studying the Wizard generated programs. They are stored in file W2 (unless you have specified another Program File with the EG command). Each Wizard generated program name is preceded by the characters "W.", so if you named your program EPROSPECTS, you can examine it by typing ED W2 W.EPROSPECTS.
You may generate a Wizard Data Entry Screen with comments by using the EF command However, be careful not to exceed the item size.
For example, if the statement SKIPNUM=4 is executed in a code segment then the next Wizard field (for which your Wizard screen will request data) will be the 4th field after the current field.
If the statement SKIPNUM=0 is executed in a code segment then your Wizard Screen will request data again for the current field. You use this to stay at a particular field when your code segment has detected a data entry operator error.
Note: SKIPNUM is always = 0 at Before Field CS, thus if SKIPNUM is set to not equal 0 then that will be the number of fields skipped.
Note: SKIPNUM can be set to +ve or -ve values thus if SKIPNUM is set to -1 then the previous field will be the next field.
ERRMSG='Your message' GOTO 2111
or
ERRMSG<1>='Your message line 1' ERRMSG<2>='Your message line 2' GOTO 2111
Here are some programming hints for Wizard screens:
This makes it easier to maintain and debug, as most of your code will be in the one place. Also if you have some code in the wrong Code Segment then you only need delete the GOSUB from the wrong Segment and add it to the correct Segment.
Therefore User Defined Code Segment could look like:
001 110 * Before Field :- ACCOUNT.NUMBER 002 *------ 003 Your code 010 RETURN 011 *------ 012 120 * Input Conversion :- CUSTOMER.CODE 013 *------ 014 Your code 030 RETURN 031 etc...
001 # TEMP = CUST.NAME 002 IF TEMP = 'CONSTANT' THEN ...
In the above example Wizard will produce two lines of code for the line 001, as follows:
CUST.NAME = INPUT.ITEMS FIRSTBUF(FN(I))<... TEMP = CUST.NAME
Code Segments allow you to change the PICK-BASIC code that Wizard generates for one program. However, Wizard also allows you to change the code that Wizard generates for all programs.
Warning: If you change these templates you will cause problems when you upgrade to a newer version of Wizard because your changes will not automatically be copied to the new templates, and the old ones will be out of date. If you do want to change these templates, be sure to document the changes carefully!
In the WUTIL file, you will find items called DMAIN1 and DMAIN2. These are the Wizard data entry screen templates. They contain most of the code that is generated in every Wizard data entry screen
To change the code that Wizard generates for all data entry screens, change DMAIN1 or DMAIN2. For instance, let us say that you wanted to change the exit command from
If you wanted to add a new field command, you would probably add the code to subroutine 2100 in DMAIN1, where all Wizard field commands that start with / or ? are processed.
If you wanted to add a new Acceptance Prompt command, you would add the code to routine 2200 in DMAIN1, where all Wizard Acceptance Prompt commands are processed.
If you want to delete a command, it is probably a good idea to comment out the code rather than actually delete it. You might change your mind. Put the comment asterisks after the first seven characters in the lines that you want to comment out. These characters are the features specification (see discussion below).
In the WUTIL file, you will find items called RMAIN1 and RMAIN2. These are the Wizard report templates. They contain only a small percentage of the code that is generated in Wizard reports.
However, RMAIN1 can be changed just like DMAIN1 or DMAIN2. RMAIN2 only contains a date and can be ignored.
The first seven characters that are at the beginning of every line in the templates are called the features specification. They tell the generator when to include the template line of code in a program that is being generated.
For instance, if a line of code in DMAIN1 starts with _______, that line of code is included in every Wizard data entry screen that is generated.
If a line of code in DMAIN1 starts with _03____, that line of code is included in every Wizard data entry screen that has feature 3 turned on.
If a line of code in DMAIN1 starts with _03&_69, that line of code is included in every Wizard data entry screen that has feature 3 and feature 69 turned on.
The format for this code is as follows. It must match the template nnnsmmm where:
| nnn | This is a feature number preceded by either _ (which is ignored) or ~ (tilde), which tells the Wizard generator process that this line is to be included if this feature is not on. So ~61 is the opposite of _61. |
| s | This is a sign - it can be either & or !. & means that the first and second feature numbers must both be selected, whereas ! means that either the first or second feature can be present for this line of code to be included. |
| mmm | This is a second feature number. The format of this is the same as that of the first (see under nnn above). |
If you are only going to change or comment out lines in the templates, then you do not need to know anything about the features specification. If you are going to add lines of code to the templates, you can start every line with _______.
For the really technically minded: the first 20 or so template features are controlled by the user defined features of the EF command (Edit Features) in Custom Wizard. Feature 3 in the EF command happens to be feature 3 in the templates, but do not count on this correlation being maintained throughout the screen. The other template features are automatically turned on when various capabilities of Wizard are used. For instance, feature 61 is turned on if any Line Item Sets are specified.
Let us say that you would like to add a customised heading to all of your Wizard Screens. Do the following:
You edit WUTIL DMAIN2. At the bottom of this item is the subroutine 100000 which displays the screen picture for Wizard Screens. At the top of this routine you can add the line:
_______ PRINT @(0,0):TIMEDATE():
or whatever you would want as the heading for all your screens. Note that to implement any changes to the templates you will need to regenerate all the Wizard screens.
This could be achieved on an individual screen basis using the Display Time Code Segment.
Note that instead of using a fixed text string for your Company Name, you could use a READ statement to read in some text from an item in a file. This would make it possible to have different text on different accounts.