KBL Help

 

KBL User Help

Language, Concepts & Techniques

 

 

 
 

KBL Language and Studio Basics

What is a KBL Script?

Working with MAIN, STORE and User-NAMED Datasets (Tables)

Organising Your Scripts by Project

Documenting and Commenting KBL Scripts

Organising Scripts by SECTIONS

Intellisense Command Prompts

How KBL Commands are Structured

Data: Bringing your Data into KBL Studio

Data: Using Kegsoft's Example Data

Introduction to working with Parameters in KBL

KBL Studio Environment Settings

 

 KBL Techniques

How to Test and Run your KBL Scripts

Reading different Data File Formats with the IMPORT Command

Writing out different Data File Formats with the EXPORT Command

Using Basic User Interface (UI) Commands: TAB.SHOW, MSG and STANDARD.INPUT

Creating business logic with IFs, GOTOs and LOOPs

User Interface Commands: DISPLAY and INPUT

Enhancing your User Interface (UI) forms with STYLESHEETS

Manipulating and Analysing Text Strings in KBL

Working with whole Records (rows)

Big Data: Working with Very Large Datasets (500K to 5M records) in KBL

 

Topic: Organising Your Scripts by Project

 

Kegsoft Projects are used to organise KBL scripts. When you write a script it's usually for a business objective - whether for a one-off utility, part of a suite of functions or an application. It might be that you are developing solutions for a client. Simply put, a KBL project is a grouping mechanism that allows you to organise scripts by project or theme. In KBL Studio Express (KSE) a project is just a name to which scripts are attached examples could Include Test_scripts, MAILING2018, Sales_Analyses. Names can be upper and lower case but should not contain any spaces. Create as many projects as you need and you can include a script in multiple projects.

Creating a new Project

To create a new project, go to the top menu line and click Project > New and a box will present for you to enter a new project name. When done, your current project will disappear and all the open script tabs disappear too.

KBL Projects

Attaching a KBL Script to a Project

To attach a script to your new project, simply open a script (Script > Open Script) and save it (alternatively, start a new script and close it). The named script will now be attached to your project. Note, a script can be attached to multiple projects.

You can leave your new script (or newly opened script) open in your project (appears as a script tab) or if your tabs line is getting crowded, close a script or two (Script > Close Script). If you do close scripts, they remain attached to the project and can be re-opened by Script > Recent Scripts.

If you are opening / closing scripts or moving between projects, it's good practice to save your work as you go (click Save to save current open script, Save All to save all changes to open scripts).

Moving Between Projects

Simply Project > Recent Projects (or Project > Open if the project was closed) and the focus will move to the selected project with any open scripts appearing along the script tab line.

Unless you have only the evaluation copy of KSE (limited to one project), you can create as many projects as you need each of which can have as many scripts as you need.

Use Projects liberally to organise your scripts

You will find projects a useful way of grouping scripts by theme or purpose. Foe example, for trying new techniques and methods create a project called 'Sandpit' or 'Experimental'..

In later versions of Studio (e.g. KSP) the project functionality will be extended as applications with required script components have more significance and need a greater level of control and governance.

 

Back to top

 

Topic: Intellisense Command Prompts

 

KBL Intellisense gives you interactive prompts when inserting command lines into your script. As soon as a recognisable command is entered, followed by a space, the prompt box will appear to indicate what the next option or element of the command should be entered. For example, you want to eliminate rows in MAIN where, say Col 1 has a particular characteristic,  after typing in MARK c.1, the box intellisense appears with the next term / option

Intellisense_1

Just click on the option you want (or just type it in) and the next space you enter will prompt the next option.

Intellisense_2

For commands that have numerous terms and options, for example PAR, COL and MARK, Intellisense is an invaluable aid as you don't need to learn and remember them all. When there are no more options to prompt, //end will normally appear (note some commands are open ended and will not provide //end), if this appears you can add a // line comment if you wish.

Note, most commands are abbreviated to a single word (e.g. MARK, COL, PAR, etc) and do not require the full Family.Set.Command structure. This is where a command is unique across all command sets and is therefore unambiguous. Where a command shares the same name in different sets, the set prefix name (and sometimes family) has to be entered for it to be recognised before intellisense will provide options (e.g. TAB.SHOW, INPUT.SHOW).

The intellisense box will disappear when an option is completed but if you want to close a prompt, use the Escape (Esc) key or click the x on the dialogue box.

Turn Intellisense off?

Note, you can turn Intellisense on/off via System > Settings > Intellisense button clicked.

Back to top

 

Topic: KBL Commands Structure

 

Three Command Levels

KBL commands are structured in three levels and take the form Family.Set.Command. For example, COL (the command to operate on a column in MAIN) has a full structure of TAB.TAB.COL, and a graph command GRAPH.PIE.SHOW.  This is because commands are grouped by functional type and what they do.

Command Structure

On the right hand side of Studio, you will see this command hierarchy and a single click on a family or command set will display the commands available within. Single click on a Family or a Set and the commands associated with the highlighted set will be displayed in the Commands box 

Using the commands

The majority of basic commands have unique names so their full hierarchy name does not need to be used in a script as there is no ambiguity in their use or they have been defaulted to mean a particular family or set. For example, in the TAB commands, COL, MARK, PAR, CLONE are used on their own. Some commands, however, do need their Command set prefix because there are commands of the same name in other sets for example SHOW, which is used in GRAPH, TAB, INPUT, DISPLAY etc. This may seem confusing initially, but its not when you get used to writing KBL as the Help and examples, all show the correct usage and there it is quite logical when you get used to it. If in doubt, when writing KBL, if you double-tap a command on the left-hand bottom of the KSE screen, the help box will be revealed showing how the command should be used in scripts - with examples.

Why are there different command families?

These are the top level command groupings that have different usages. In KSE, the standard Families include:


TAB For manipulating columns, rows and cells in MAIN, STORE and user-defined Tables
SYSTEM Commands that work on parameters (variables) and non dataset controls
UTIL    Utility functions
GRAPH Graphical commands
STANDARD Set functions used for application-building functions

Note, in KBL Studio Plus (KSP), there are additional command families that are used for strategic system and application building. Be aware that any script created in KSE will run in KSP, but scripts developed in KSP using its additional command sets, will not run in KSE.

Back to top

 

Topic: Commenting KBL Scripts

  

Adding comments, notes and REMarks is an important part of script writing. Documenting your script is a discipline not to be neglected as good comments and descriptions improve both yours and other peoples understanding of the logic and functionality. Good commenting assists both peer review and future maintenance. Adding comments is easy.

There are three different ways of adding comments to your script in KBL, in all cases they are ignored by the KBL script processor. You can add whole line comments, in-line comments and block comments.

Commenting KBL SCripts

REM This a comment line

Comment lines starting with REM and a space can be used anywhere in a script but particularly at the start where you may wish to add the script author, date, version and a brief description. When the script colouring is turned on, REM comments appear as green text.

// This is a whole comment line

Two forward slashes followed by a space are the easiest and the most common comment method used in KBL, it is quick to do and allows the user to add comments anywhere on the script. When you are developing a script, you may wish to temporarily comment out a line with a // prefix.

// Comment added at end of a command line

// followed by a comment or note can be added after a command on the same line (for most commands). This method is widely used for a short note to explain what the specific command has been used for and why, also used to add notes to the script for future understanding.

{ Block comment}

Curly Brackets, these are a handy way of commenting out a block of text, command script or combination. Just place them around a section in the script and the KBL processor skips past the bracketed out section. They can be used anywhere, including parts of a line, even within a command string. Very useful for developing script, as whole sections of script can be taken out of action while testing or editing.

Back to top

 

Topic: Data - Importing Your Data into KBL Studio

 

To use your own data files (.XLSX, .txt, etc.) you need to bring it into the KBL Studio environment. Use the top menu System > Bring In facility which allows you to browse to the items you want.

Studio will automatically put data files into the standard /Data folder  - which can be viewed with System > Folders > Data

Images

Note that if you ˜Bring In" Image Files (.png and .jpg), Studio will automatically put them in your /PIC folder.

Exporting

If you export your results to a spreadsheet or Keg file with the EXPORT command, the files will be created in the /Data folder.

Big Data

NOTE: Normally the location for your data files is the /Data folder. However, KBL can read (and write) data in the > 1Gb range (e.g >1 million rows) so it may not be satisfactory to put very large files in /Data but locate them in a more appropriate folder structure. The FILE command set is able to use other folder locations. See separate help documentation for more specialist handling of large datasets here.

 Back to top

 

Topic: Data - Using Kegsoft's Example Data

 

When you install KBL Studio, a number of example scripts are included for you to look at and run (accesses through Studio Command Help facility). These examples use data files which are also included in the download. They are not installed in the usual /Data folder but with other Studio operating components in KSE's /bin file (never delete any files from the /bin file unless advised to by Kegsoft). To use the example files which comprise both Excel (.XLSX) and Kegsoft's own datafile format (.keg), you need to prefix the IMPORT command with ex: (as you will see in the example scripts).

The main example files, both .xlsx and .keg correspond to a typical business scenario of Customers, Orders and Products together with some “reference codes”.  The files comprise


ccc_customers.xlsx
ccc_oders.xlsx
ccc_products.xlsx
ccc_ref_codes.xlsx

Note, although the data have some matching keys (Cus_id) for data Merging exercises, it is not a perfect ˜relational" model and the content has deliberate errors to exercise example logic.

You can use these for files for your own testing purposes.

Reminder, to use one of the set example files, you need to prefix the file name with ex: in the IMPORT command (not needed for your normal files in /Data file). E.g.

IMPORT /XLSX ex:ccc_customers Worksheet=Sheet1 // to use an example file

IMPORT /XLSX my_customers Worksheet-Sheet1    // using a data file you have brought in to /Data

Back to top

 

Topic: Script Sections

 

By their very nature, components of business logic and process flow comprise blocks of discrete logic either organised consecutively or called upon under certain conditional scenarios. A KBL script may comprise just such a collection of interconnected logic blocks. It is good practice to clearly label these components. They are formally known as Sections in KBL and can be labelled with the SECTION statement and typically used thus:


// --------------------------------------
SECTION NON-UK-CUSTOMERS
// --------------------------------------

Note that spaces should not be used in Section names

They perform no function in KBL logic other than to indicate to the user that they are discrete components. However, they can be used to navigate through a script. There is a Sections button on the top menu bar of Studio, if you have used Sections, they will appear as pull-down list. Click on a section and the cursor will jump to the section heading.

If you click the Colour menu item button, which colours certain command types, Sections appear as yellow.

You can create as many sections as you want, they are great for tidying up your script and labelling all of the different parts and giving a brief description of what part they play. If you tend to write long scripts, scripts for customers or peer review, we recommend organising your work as identifiable sections.

SECTION INPUT-DATA

SECTION User-Input

SECTION PROCESS-DATA

SECTION DATA-ANALYSIS

SECTION Export-Data-Files

 

Back to top

 

Topic: Introduction to KBL Parameters

 

This is a big subject and so this is just an introduction

Parameters in KBL are individually named, single data items with a value. Traditionally, parameters are static items used for control and calculation purposes E.g. VATRate, BankRate, Pi, or any other value of purpose that's used in a program. However, KBL is not prescriptive and so a parameter is literally just a single data item that can be static or changed whether used for input or output or control purposes, be it a text string or a numeric item (integer or real) or a date. Examples:

PAR Name = "John Smith"    // Text string

PAR DateOfBirth = 21/09/1994 // Par as a date

PAR Interest_Rate = 2.75 // Real number

PAR MAX_ATTEMPTS = 5    // Integer number

PAR CONTINUE = YES // A parameter used for control purposes

PAR Check TRUE    // Used as a "Boolean" setting

There are two principal commands that explicitly create and operate on parameters: PAR which is generally used to set an initial value and PAR.VAR which handles more complex and subtle data manipulations.

var.par LuckyNum  = /GEN RANDOM 1 1000    // parameter is a random no. between 1 & 1000

Additionally, some parameters are created implicitly by the KBL processor (e.g. the number of rows in a table, dates, the user's UserId, etc.) and there are some utilities such as date format manipulators that also operate on parameters. When a command or technique generates a parameter, it will be noted in the command documentation for example, when a control button on an input form is clicked, a return parameter is created for you to test the response, click the OK button and [INPUT_CLICKED] will return OK, if Cancel is clicked [INPUT_CLICKED] returns CANCEL..

If you master the use of parameters you will have a very good grasp of KBL and will be able to perform sophisticated IT tasks. A key feature of parameters is that they are very "literal", they are not designated a type (number, text string or date) and their usage is very flexible.

Lets look at some simple examples:

PAR myname = "Harry Kiri" // A parameter can be assigned in upper or lower case
MSG "Your name is [MYNAME]" // But always referred to in uppercase, in square brackets

Above we created a parameter call myname with a value "Harry Kiri", then we displayed in a message "Your name is Harry Kiri". Note, unless advised otherwise (in a specialised command), parameters are referred to and used between square brackets and in upper case. Parameters will not be recognised as such in mixed or lower case. Also note, parameter names must not contain any spaces.

We could have specified the following

PAR Firstname = "Harry" // parameter set with a lireral value
PAR SecondName = "Kiri"
PAR FullName = "[FIRSTNAME] [SECONDNAME]"    // Par set with other parameters embedded
PAR Age = 28
MSG "Your first name is [FIRSTNAME], your second is [SECONDNAME], your fullname is [FULLNAME] and your age = [AGE]"

Which would give a message of

Parameters in a text string

Some Maths

To do maths on a parameter, its value must be numeric with no alphabetic characters

VAR.PAR AGE = /MATHS PLUS 10 // Add 10 to Age

The new value for Age will be 38, (initial value of 28 + 10) but in the context of the following command, its treated as text!

MSG "[FIRSTNAME], in 10 years time, your age will be [AGE] "

Some Conditional Logic

IF IS [AGE] < 21
  MSG "[FULLNAME] you are too young"
IF ELSE
 MSG "[FULLNAME] you are eligible for a discount"
 EXIT
IF END

Another one:

IF "[FULLNAME]" Contains "Harry"
 MSG "Welcome Harry"
IF END

Note the use of quotes around [FULLNAME] this is because this parameter has, or could contain a space in the text and any text that contains spaces must be enclosed in quotes. As parameters are treated literally, it makes no difference that the string being processed resides in a parameter.

An key feature of KBL is that parameters can substitute literal values in Commands, any component of a command that requires a literal value, e.g. a row number, a text string, a column number can also accept a parameter. E.g.

SET /TABVAR MAIN c.2 3 London    // this puts the value "London" in MAIN dataset, Column 1, row 3

The following will have exactly the same result:

Par TABLE = MAIN
PAR COLUMN = 2
PAR Row = 3
PAR Town = "London"

SET /TABVAR [TABLE] c.[COLUMN] [ROW] [TOWN]    // Value entries can be replaced by parameters

Obviously, its unlikely that anyone would write such code to set the parameters like this; however, if the SET command, used to update a cell in a dataset was within a LOOP that controlled the record number (row), the value for Town came from an INPUT form, then writing your script "generically" makes sense.

Just to reiterate the basics:

1. When their values are being used in other commands, parameters are represented in square brackets in uppercase [MY_VALUE]

2. When setting a parameter to a text string, put quotes around it "This is a string" and if a parameter contains text with spaces (or likely to do so), Put quote marks around the parameter e.g. "[A_PHRASE]".

3. KBL will determine what to do with a parameter from its value BUT make sure if you use a maths command ensure it is numeric or if you want to reformat a date, ensure it corresponds with the expected date format.

When in doubt look at the examples.

Back to top

 

Topic: Testing Your KBL Scripts

 

One of the great features of KBL is the ease with which you can develop, test and review scripts. By testing your work as you write it, the process of building even large applications in KBL keeps your complexity down as you are effectively writing and testing your logic incrementally.

The KBL processor gives you access to all the information in play at every command step. By this we mean:

  • The point in the script (code) you have reached
  • The current contents of all the in-memory datasets. Just Click on the MAIN, STORE and NAMED table icons on the command menu line 
  • The current values of parameters you and the processor have created. Just click on the PARAMETERS icon

There are Three run modes, activated by icons on the Studio command menu line

KBL Running and Testing

Run- This runs the current script in its entirety from start to end. If there are errors the process will stop on the first error to occur and report the problem. Unless you have deliberately cleared the in-memory datasets (MAIN, STORE and user defined) and parameters, you will be able to view these contents either at the end-point of the script or at the point of failure. Note that errors are usually reported on the bottom line of Studio, in red

Step- As the name implies, this command executes one command line at a time and halts on the next. If an error occurs, it will be reported. You can view the contents of current datasets and parameters at any point. You can proceed through your script as quickly as needs be by clicking Step. Be aware, if you decide to change a line during this process, you will need to click Reset for the change to take effect in your script and should start Stepping again OR use RunTo, then recommence Stepping where you left off. Note that some lines are non-executable (blank lines, comments, Sections, Labels) and where there is conditional logic (IFs, GOTOs and LOOP commands), the stepping will obey the logic and jump to the appropriate line (obeying the logic).

RunTo - This executes your script up to a specified line in the code. To set the line you want to stop at 1) Double Click on the line and 2) Click Reset, This sets a line number next to the RunTo and returns the cursor to the top of the script. 3) Click RunTo and your script will run up to the required point (providing no errors are reported). At you destination point you can either Reset to take you back to the top of the script or carry on executing Step by Step.

Using a combination of these run keys you can test your script as you go. If you have been asked to test someone else's script you can apply the same technique and examine the logic as finely as you need to.

Reset - The KBL process is not infallible so if you are using a combination of Step and RunTo and changing code in quite succession, use the Reset button to re-initialise the current script for a clean run. Reset clears all memory elements for your current script (MAIN, STORE and other table storage AND Parameter values) and resets the cursor to the top of your script.

Tips for testing and developing.

  • Put the right amount of commenting / documentation in your script as appropriate to whose testing or maintaining your finished script.
  • Use the SECTION command to segment your script, it does allow you to navigate through a long script quickly (click on the Sections icon to list sections).
  • When writing your script, put in temporary data and messages for debugging purposes, you can remove or comment out these later. E.g.

MSG "MyValue = [MYVALUE], Loop number [L3]"    // display parameters, OK to Continue

TAB.SHOW CUST_TABLE "Data in Cust table after editng"    // Show current data in dataset

  • Remember you can block comment out chunks of script with curly brackets { some script }, this is helpful if you are testing only certain parts of your script.
  • Don't be tempted to put too many corrections in at a time, correct your script in small increments to avoid unpredictable results.
  • SAVE your work regularly make copies of scripts, develop incrementally, there is nothing more frustrating than to having to remember changes that were lost.

Back to top

 

Topic: Studio Environment Settings

 

Changing the Text Size

For readability, you can increase or decrease the font size of the text in your current script tab by holding down the CTRL keyboard button and rolling the scroll wheel on your mouse (or use the enlarge / reduce gesture on your touchpad). For added readability click the colour icon to highlight different parts of your script.

System > Settings

You can change several environment settings via the system > settings option on the top-line menu. For the settings to take effect, they need to be saved, exit Studio then restart it.

Script Text Colour

Two colours are available: Black and Steel Blue. You can select the one you prefer.

Intellisense on or off

We recommend you leave intellisense on as it saves you from having to remember all the options when entering commands but you can turn it off if you want to. Currently, Intellisense is not fully context sensitive, there will be enhancements over time.

Show tab mode

When you inspect MAIN, STORE or NAMED memory tables using the menu items, a pop-up grid appears with the data which, by default, has to me dismissed before you can continue running (stepping through) your script. If you tick the Show Tab mode option, you can continue without having to dismiss the grid (although it has to be minimised).

Show Column type

When you use the MAIN, STORE or NAMED command icons to display the data grids, the base format of columns can be displayed (Text, Int, Real) with this option turned on.

KWIZ Auto

The KBL Wizard (Kwiz) is invoked by clicking the Kwiz icon or via Help >Kwiz, however, if you prefer, you can get it to start first each time you open Studio with the KWIZ Auto option ticked.

Tip System On

With tips on, random tips are displayed via the pull-down option symbol at the bottom of the Studio screen (down-facing arrow/triangle). Click the symbol to see randomised tips of the day

Default Studio window size (at start-up)

You might be working on a large or small screen. The default size of the Studio screen is kept as an environment setting. If you wish, you can change your default Height and Width site settings to suit. These settings will be used when you start-up KBL Studio.

Back to top