USoft Action Language

With the USoft Action Language, you can create command scripts. They are sequences of 1 or more commands. Multiple commands in a command script are separated by newlines:

command

command

The following command script commits the transaction, then gives an information message:

ActionCommit()

MessageInformation( Finished. )

Each command consists minimally of a method name. Each method name is obligatorily followed by an opening parenthesis. This parenthesis must be closed:

method()

In this product documentation, you can find methods by use case or in an alphabetic list:

Methods by use case

Methods by name

When you call a method, depending on what you need and what the method expects, you can pass 1 or more parameters. Multiple parameters are separated by commas:

MessageInformation( Finished. )

MessageLanguage( 'Admin Msg', 'WRONG_INSTANCE_NAME', 'ERROR', :1 )

Parameter values are weakly typed. As the examples show, string values may or may not be surrounded by single quotes or double quotes.

Whitespace (space, tab and newline characters) is insignificant except in values surrounded by single or double quotes. The following lines are equivalent:

MessageInformation(  Finished.   )

MessageInformation(Finished.)

In the following line, the space between Admin and Msg is part of the parameter value passed, but the space preceding the quote before Admin is insignificant:

MessageLanguage( 'Admin Msg', 'WRONG_INSTANCE_NAME', 'ERROR', :1 )

The notation colon ( : ) + name represents a placeholder for which a host variable value is substituted at runtime:

:"global.root_folder"

:person_id

The notation :1 represents the first parameter value passed to a call or the first value retrieved in a SELECT output list. :2 represents the second value passed, and so on.

Method calls in a job scripting context (as opposed to a Windows GUI context) are usually globally available methods that require no object identification:

ActionCommit()

These methods are also referred to as application methods.

Application methods are also widely used in a Windows GUI context, but there, you also require object identification. Object names precede method names. The two are separated by a full stop ( . ):

object.method( )

An object name that does not contain full stops denotes the instance of a window class, as MyPersonsWindow in:

MyPersonsWindow.ActionAllRows( action )

This example performs action for all the rows in the MyPersonsWindow window.

In Windows GUI, objects exist in a containment hierarchy. You can reach descendents in this hierarchy by placing a full stop ( . ) between each parent object and its child object. The following method call addresses the physical text box for the field corresponding to the AREA_CODE table column in the current window. Its effect is to set this text box's background color to blue:

 query.area_code.esd_char.background( red )

The physical text box is denoted by esd_char. The AREA_CODE table column is denoted by query.area_code. This example is a property call, see next section for details.

A special subset of method calls are property calls. The method name background in the following call is a property name. This call sets the background colour property of the window to a red colour:

MyPersonsWindow.background( red )

In Windows GUI, use the Object Activator tool to find the available names of objects, methods and properties within a window. For details, search "object activator" in developer.usoft.com or in the Windows Designer Guide. Search "actions examples" for more examples of command scripts in a Windows GUI context. See also the Property Reference section in this Developer Reference Guide.

To script behaviour between windows, you can pass objects of the calling window as a user-defined property of the called window. The following call demonstrates this technique:

My_Days_Property( Days( Self() ).Window.Create() )

In this technique, you need to create one or more user-defined properties in the called window class (here: the Days window class). For details, search "window interaction". This object-oriented technology, based on internal object IDs, replaces an obsolete path technology based on a hierarchy of embedding runtime windows, where <- was a navigation path to the shell of the current window, <-<- a navigation path to the shell of the parent window, and *name a wildcard navigating to the next descendent match of name, as explained to some length in the ac-rel() help topic.

In a Windows GUI context, you call the USoft Action Language from behaviour properties or event properties of window objects. For example, a Button control has an Action behaviour property where you use the USoft Action Language to write a command script that specifies what happens when the user presses the button.

In a job scripting context, you call the USoft Action Language from action tasks :

that you include in jobs :

You call also the USoft Action Language in a context where SQL is expected. Use the action keyword to express that you are calling the Action Language instead of executing an SQL statement:

A decision is a programmatic construct in USoft Definer that you can call from Windows Designer and from Action Tasks in batch jobs. Do this by calling the ActionDecision() application method. This allows you to call a command script (Yes Action) for each row retrieved by a SQL query (Decision SQL), or, if the query retrieves no rows, to call a different command (No Action) instead. If multiple rows are found, Yes Action is executed once for each row:

As the example illustrates, a decision allows you to pass variables between SQL routines and USoft Action Language commands, and also, you can pass to the decision itself a list of incoming parameter values. The example also shows that you can used decisions for error handling: the error is usually handled by the No Action.

A further possibility is to execute SQL where a command script is expected. Do this by calling the SqlScript() method.

For more details on branching and looping with decisions, and on passing parameters between SQL and Action Language commands, search "decisions" in developer.usoft.com or in the USoft Definer Help.