Tutorial 8 - Creating a User Function

Scribe comes with a set of pre-built System functions. In Tutorial 6 we already made use of one such function: IntegerToText converter. Scribe can be expanded by adding User functions to the inventory of tools. One such function will be built in this Tutorial.

Scribe's design philosophy encourages factoring out portions of flowcharts and packaging them as separate procedures that are intended to perform a specific, usually narrowly-defined function. In future Tutorials, we will need the ability to translate an arbitrary date in YYYYMMDD format to a date with the same year and month, but the day fixed at 1 (in other words, we will need to reduce any date to the first day of the month). The desired transformation should be as in the following example:

As usual, we start with a new component - this time, a User Function. Select User Functions entry in the Application Launchpad window and click on the Launch button (or just double-click the User Functions entry). Scribe will open a new ("UNTITLED") Function Workspace window. It comes preloaded with two components: Parameter and Return Value.

As the first step, select the Parameter component, add a new parameter to it and rename it to "Date" (refer to the Tutorial 4 for details). Set the parameter data type to Date.

Next, bring in a new Function component, and set it to the DateToText function (see Tutorial 6 for details). This function converts Date type to Text by taking a Date variable as input, and returning another variable of Text type. The returned date is formatted as an ASCII string according to the format selected in the function's second parameter, as shown in the following figure:

Note: the date formats shown in the function's pop-up list come from the Date Format Editor accessible through Edit > Edit Date Formats menu item. Before dragging the Function component in, open the Editor, make sure that YYYYMMDD format is listed in it, and add it to the list if necessary.

We now have the text string that we can manipulate by stripping off its tail-end portion (the DD part of YYYYMMDD format) and replacing it with '01' to set the date to the first day of the given month. To do this, we will use another System function: Substring. This function extracts parts of text string carried by the variable passed as the first input parameter, based on the start and end index values passed in the 2nd and 3rd parameter. We want to extract the first 6 characters of the string (the YYYYMM part), so the indices are 0 and 5 (they are 0-based, which means that the first character has index 0, the second character has index 1, etc.).

Once we have the text string with year and month, we can concatenate a string literal '01' to it, using the Calculation component, and end up with the text string that contains the desired date (in text form):

By the way, this is the first time we used the Hub component. Hubs are do-nothing components that serve as a convenience for making connection in tight spots, where drawing direct lines would result in overlapping with other components or connecting lines.

To complete the procedure, we bring in another System function: TextToDate. The function takes a text string that contains a date in in YYYYMMDD format, and returns a variable of DATE type with the same date value. It is a simple data type converter that provides a variable of the required data type that can be returned by the User Function to the outside world:

The Return Value component is set to the Date-type variable (YearMonthDate) formatted by the TextToDate function; this is done by selecting the component and then clicking on YearMonthDate variable name in the Palette, or dragging it into the Return Value component.

We should check the syntax of our newly created flowchart, and then test the function.