Runtime external object

Official Content
This documentation is valid for:

The GeneXus.Common.Runtime external object allows the developer to get or set specific runtime properties, with different purposes.

Properties

Environment property

It allows the developer to differentiate, at runtime, when the application executes some action on the client-side or on the server-side. Its purpose is to allow the developer to make decisions programmatically to be consistent with the business logic of the system (e.g. determine the insert timestamp of a new record, which can differ between the client or the server during the synchronization).

It is based on the RuntimeEnvironment domain (described below) that provides the environment information in which the called action was executed.

  SD Online SD Offline Web
Start event Server Device Server
Refresh event Server Device Server
Load event Server Device Server
Procedure object Server Device Server
Business Component rules Server Device Server
ClientStart event & Navigation Start events Device Device N/A
User defined event Device Device Browser

RuntimeEnvironment domain

It is an enumerated domain describing possible runtime environments.

Server Server-side
Device Client-side on the Smart Device environment
Browser Client-side on Web environment.

ExitCode Property

This property allows setting the exit code (also known as errorlevel) of a process when it terminates, specifically, the one of a procedure with Call protocol property set to 'Command Line'. It is typically used to control the flow of batch programs.

The default value is 0.
The exit code of a process that terminates abnormally (with an exception) is 1.

Note: The exit code set by the terminated program can be read using the '%ERRORLEVEL%' variable in a Windows batch file and the '$?' in Linux shell.

See also

Examples

This section provides some simple use cases where the Runtime external object might be useful.

  1. Environment Property - Gap during synchronization
    In an offline smart device application, when a new record is inserted in the database, this record will adopt the device timestamp (the real one), but after the synchronization, the server will persist another. This problem can be avoided if the developer takes control when the record is physically inserted.

    Suppose you have the following transaction:
    Task
    {
       TaskId*      : Numeric(4.0)
       TaskAbstract : Character(200) 
       TaskCreated  : DateTime
    }
    Rules
       noaccept(TaskCreated);
       TaskCreated = now() if insert;
    
    If the application is offline, which will be the TaskCreated timestamp value? The moment when the record is inserted on the offline database or when is inserted in the server database? For avoiding this problem, you can include TaskSynced attribute (DateTime base too), and differentiate both cases as follows:
    Task
    {
       TaskId*      : Numeric(4.0)
       TaskAbstract : Character(200) 
       TaskCreated  : DateTime
       TaskSynced   : DateTime
    }
    Rules
       noaccept(TaskCreated);
       noaccept(TaskSynced);
       TaskCreated = now() if insert and Runtime.Environment = RuntimeEnvironment.Device;
       TaskSynced  = now() if insert and Runtime.Environment <> RuntimeEnvironment.Device;
    
  2. Environment property - Offline notifications
    When a smart device application works in an offline architecture, the process for sending notifications must be controlled in order to be sent by the server (not the device). This problem can be avoided analogously to the use-case (1) by restricting the execution to only when it's from the server (RuntimeEnvironment.Server).
  3. ExitCode property - Setting Errorlevel
    The following procedure returns exit codes (and writes to the console) as follows
    If data could be saved successfully: The procedure sets exit code 0 and writes to the console "Data has been saved successfully"
    If data could not be saved: The procedure sets exit code 2 and writes to the console "Data could not be saved"
    If a not handled exception occurs (eg. the 'Client BC' has a division by zero): The procedure sets exit code 1 and writes to the console the details of the exception
    &Client.Id = 1
    &Client.Name = "John"
    &Client.Save()
    If &Client.Fail()
        rollback
        msg("Data could not be saved",status)
        GeneXus.Common.Runtime.Exitcode = 2
    else
        commit
        msg("Data has been saved successfully",status)
    endif

Scope

Platforms SmartDevices(Android, iOS), Web (Java, .NET)

Availability

This external object is available as from GeneXus 15.
ExitCode Property is available as from GeneXus 16 upgrade 5.