Context information

Application Techniques
Using External Functions and Other Processing Extensions

Context information service
Context keyword service
Error logging service
Internet service
Transaction server service

The PowerBuilder context feature allows applications to access certain host (non-PowerBuilder) services. This is a PowerBuilder implementation of functionality similar to the COM QueryInterface. PowerBuilder provides access to the following host services:

PowerBuilder creates service objects appropriate for the current execution context (native PowerBuilder or transaction server). This allows your application to take full advantage of the execution environment.

The context feature uses seven PowerBuilder service objects: ContextInformation, ContextKeyword, CORBACurrent, ErrorLogging, Inet, SSLServiceProvider, and TransactionServer; it also uses the InternetResult object. (The context feature is sometimes called the Context object, but it is not a PowerBuilder system object.)

For more information about these objects, see Objects and Controls or the section called “Browsing the class hierarchy” in Users Guide.

Enabling a service

Before you use a service, you instantiate it by calling the GetContextService function. When you call this function, PowerBuilder returns a reference to the instantiated service. Use this reference in dot notation when calling the service's functions.

To enable a service:

Establish an instance variable of the appropriate type:

ContextInformation icxinfo_base
ContextKeyword     icxk_base
CORBACurrent       corbcurr_base
ErrorLogging       erl_base
Inet               iinet_base
SSLServiceProvider sslsp_base
TransactionServer  ts_base

Instantiate the instance variable by calling the GetContextService function:

this.GetContextService("ContextInformation",  &
   icxinfo_base)
this.GetContextService("ContextKeyword", icxk_base)
// Use Keyword instead of ContextKeyword 
this.GetContextService("Keyword", icxk_base) 
this.GetContextService("CORBACurrent", &
   corbcurr_base)
this.GetContextService("ErrorLogging", erl_base)
this.GetContextService("Internet", iinet_base)
this.GetContextService("SSLServiceProvider", &
   sslsp_base)
this.GetContextService("TransactionServer",ts_base)

Using a CREATE statement

You can instantiate a service object with a PowerScript CREATE statement. However, this always creates an object for the default context (native PowerBuilder execution environment), regardless of where the application is running.

Context information service

You use the context information service to obtain information about an application's execution context. The service provides current version information, as well as whether the application is running in the PowerBuilder execution environment.

Accessing context information

Using the context information service, you can access the information in the following table.

Item	Use this function	Comment
Full context name	GetName	Value returned depends on the context: Default: PowerBuilder Runtime
Abbreviated context name	GetShortName	Value returned depends on the context: Default: PBRUN
Company name	GetCompanyName	Returns Appeon.
Version	GetVersionName	Returns the full version number (for example, 2019.0.1)
Major version	GetMajorVersion	Returns the major version number (for example, 2019)
Minor version	GetMinorVersion	Returns the minor version number (for example, 0)
Fix version	GetFixesVersion	Returns the fix version number (for example, 1)

Using the ClassName function for context information

You can also use the ClassName function to determine the context of the object.

You can use this information to verify that the context supports the current version. For example, if your application requires features or fixes from Version 2019.0.1, you can use the context information service to check the version in the current execution context.

To access context information:

Declare an instance or global variable of type ContextInformation:
```
ContextInformation icxinfo_base
```
Create the context information service by calling the GetContextService function:
```
this.GetContextService("ContextInformation", &
   icxinfo_base)
```

Call context information service functions as necessary.

This example calls the GetShortName function to determine the current context and the GetVersionName function to determine the current version:

String  ls_name
String  ls_version
Constant String ls_currver = "12.5.0.1"
icxinfo_base.GetShortName(ls_name)
IF ls_name <> "PBRun" THEN
   cb_close.visible = FALSE
END IF
icxinfo_base.GetVersionName(ls_version)
IF ls_version <> ls_currver THEN
   MessageBox("Error",  &
      "Must be at Version " + ls_currver)
END IF

Context keyword service

Use the context keyword service to access environment information for the current context. In the default environment, this service returns host workstation environment variables.

Accessing environment variables

When running in the PowerBuilder execution environment (the default context), you use this service to return environment variables.

To access environment variables:

Declare an instance or global variable of type ContextKeyword. Also declare an unbounded array of type String to contain returned values:
```
ContextKeyword  icxk_base
String   is_values[]
```
Create the context information service by calling the GetContextService function:
```
this.GetContextService("Keyword", icxk_base)
```
Call the GetContextKeywords function to access the environment variable you want. This example calls the GetContextKeywords function to determine the current application Path:
```
icxk_base.GetContextKeywords("Path", is_values)
```
Extract values from the returned array as necessary. When accessing environment variables, the array should always have a single element:
```
MessageBox("Path", "Path is: " + is_values[1])
```

Error logging service

To record errors generated by PowerBuilder objects running in a transaction server to a log file, create an instance of the ErrorLogging service object and invoke its log method. For example:

ErrorLogging erlinfo_base
this.GetContextService("ErrorLogging",  &
   erlinfo_base)
erlinfo_base.log("Write this string to log")

The errors are recorded in the Windows system application log if the component is running in COM+.

Internet service

Note

Inet object is considered to be obsolete. Obsolete features are still available to use, but are no longer eligible for technical support and will no longer be enhanced. You can replace it by using the WebBrowser control or the HTTPClient object.

Use the Internet service to:

Display a Web page in the default browser (HyperLinkToURL function, which starts the default browser with the specified URL)
Access the HTML for a specified page (GetURL function, which performs an HTTP Get)
Send data to a CGI, ISAPI, or NSAPI program (PostURL function, which performs an HTTP Post)

Hyperlinking to a URL

You call the Internet service's HyperLinkToURL function to start the default browser with a specified URL.

To hyperlink to a URL:

Declare an instance or global variable of type inet:
```
inet  iinet_base
```
Create the Internet service by calling the GetContextService function:
```
THIS.GetContextService("inet", iinet_base)
```
Call the HyperLinkToURL function, passing the URL of the page to display when the browser starts:
```
iinet_base.HyperlinkToURL  &
   ("https://www.appeon.com")
```

Getting a URL

You call the Internet service's GetURL function to perform an HTTP Get, returning raw HTML for a specified URL. This function returns the raw HTML using the InternetResult object.

To perform an HTTP Get:

Declare an instance or global variable of type Inet. Also declare an instance or global variable using the descendant InternetResult object as the datatype (n_ir_msgbox in this example):
```
Inet iinet_base
n_ir_msgbox  iir_msgbox
```
Create the Internet service by calling the GetContextService function:
```
THIS.GetContextService("Internet", iinet_base)
```
Create an instance of the descendant InternetResult object:
```
iir_msgbox = CREATE n_ir_msgbox
```
Call the GetURL function, passing the URL of the page to be returned and a reference to the instance of the descendant InternetResult object:
```
iinet_base.GetURL  &
   ("http://www.appeon.com", iir_msgbox)
```
When the GetURL function completes, it calls the InternetData function defined in the descendant InternetResult object, passing the HTML for the specified URL.

Posting to a URL

You call the Internet service's PostURL function to perform an HTTP Post, sending data to a CGI, ISAPI, or NSAPI program. This function returns the raw HTML using the InternetResult object.

To perform an HTTP Post:

Declare an instance or global variable of type Inet. Also declare an instance or global variable using the descendant InternetResult object as the datatype (n_ir_msgbox in this example):
```
Inet  iinet_base
n_ir_msgbox  iir_msgbox
```
Create the Internet service by calling the GetContextService function:
```
THIS.GetContextService("Internet", iinet_base)
```
Create an instance of the descendant InternetResult object:
```
iir_msgbox = CREATE n_ir_msgbox
```

Establish the arguments to the PostURL function:

Blob    lblb_args
String  ls_headers
String  ls_url
Long    ll_length
ls_url = "http://coltrane.appeon.com/"
ls_url += "cgi-bin/pbcgi80.exe/"
ls_url += "myapp/n_cst_html/f_test?"
lblb_args = Blob("")
ll_length = Len(lblb_args)
ls_headers = "Content-Length: "  &
   + String(ll_length) + "~n~n"

Call the PostURL function, passing the URL of the routine to be executed, the arguments, the header, an optional server port specification, and a reference to the instance of the descendant InternetResult object:
```
iinet_base.PostURL  &
   (ls_url, lblb_args, ls_headers, 8080, iir_msgbox)
```
When the PostURL function completes, it calls the InternetData function defined in the descendant InternetResult object, passing the HTML returned by the specified routine.

Using the InternetResult object

The GetURL and PostURL functions both receive data in an InternetResult object. This object acts as a buffer, receiving and caching the asynchronous data as it is returned by means of the Internet. When all data is received, the InternetResult object calls its InternetData function, which you override to process the data as appropriate.

Implement in descendants of InternetResult

You implement this feature by creating standard class user objects of type InternetResult. In each of these descendant user objects, define an InternetData function to process the passed HTML as appropriate.

To implement a descendant InternetResult object:

Create a standard class user object of type InternetResult.
Declare a new user object function as follows:
- Name
  
  InternetData
- Access
  
  Public
- Returns
  
  Integer
- Argument name
  
  Data, passed by value
- Argument datatype
  
  Blob
Add code to the InternetData function that processes the returned HTML as appropriate. This example simply displays the HTML in a MessageBox:
```
MessageBox("Returned HTML", &
   String(data, EncodingANSI!))
Return 1
```

Transaction server service

Use the transaction server service to access information about the context of an object running in a transaction server. You can use the TransactionServer object to influence transaction behavior programmatically, and to access the methods of another component on the transaction server.

Prev	Up	Next
The Message object	Home	Developing Distributed Applications

Application TechniquesUsing External Functions and Other Processing Extensions