Runtime external object

Official Content
This documentation is valid for:

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



Environment property

It allows you to differentiate, at runtime, when the application executes some action on the client-side or on the server-side. Its purpose is to allow you 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.

  Online Native Mobile applications architecture Offline Native Mobile applications architecture 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 Native Mobile or Angular 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.


The runtime external object allows you to read the generic environment variables you have defined. To achieve this, you can use the following methods:


Returns the value of the environment variable. If it does not exist, returns EMPTY.

Return value VarChar
Parameters   VarName:VarChar


Returns True if, and only if, the environment variable exists (<> NULL).

Return value Boolean
Parameters   VarName:VarChar


Returns all environment variables defined.

Return value Properties Data Type
Parameters   None


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

  1. Environment Property - Gap during synchronization
    In an offline Native Mobile 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 you take control when the record is physically inserted.

    Suppose you have the following transaction:
       TaskId*      : Numeric(4.0)
       TaskAbstract : Character(200) 
       TaskCreated  : DateTime
       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:
       TaskId*      : Numeric(4.0)
       TaskAbstract : Character(200) 
       TaskCreated  : DateTime
       TaskSynced   : DateTime
       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 Native Mobile 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"
    If &Client.Fail()
        msg("Data could not be saved",status)
        GeneXus.Common.Runtime.Exitcode = 2
        msg("Data has been saved successfully",status)
  4. To get an environment variable, you can use HasEnvironmentVariable and GetEnvironmentVariable as follows:
         &VarName = Runtime.GetEnvironmentVariable("VAR_NAME")
  5. If you want to get all the environment variables, you should do something like the following:
    &AllEnvironmentVars = Runtime.GetEnviromentVariables()//&AllEnvironmentVars is of Properties data type
    for (&EnvionmentVariable in &AllEnvironmentVars)
        msg(Format(!"%1:%2", &EvironmentVariable.Key, &EvironmentVariable.Value))


Generators: Java.NETAndroidApple

See Also

Error_Handler command
Exception Handling in Genexus