Runtime external object

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

Properties

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.

RuntimeEnvironment domain

It is an enumerated domain describing possible runtime environments.

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.

Methods

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

GetEnvironmentVariable

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

Return value VarChar
Parameters   VarName:VarChar

HasEnvironmentVariable

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

Return value Boolean
Parameters   VarName:VarChar

GetEnviromentVariables

Returns all environment variables defined.

Return value Properties Data Type
Parameters   None

Samples

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:

   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 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"
   &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

4. To get an environment variable, you can use HasEnvironmentVariable and GetEnvironmentVariable as follows:

   if(Runtime.HasEnvironmentVariable('VAR_NAME'))
        &VarName = Runtime.GetEnvironmentVariable("VAR_NAME")
   endif

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))
   endfor

Scope

Generators: Java, .NET, Android, Apple

See Also

Error_Handler command
Exception Handling in Genexus