Application Techniques
Program Access Techniques

To declare an external function:

1. If you are declaring a local external function, open the object for which you want to declare it.

2. In the Script view, select Declare in the first drop-down list and either Global External Functions or Local External Functions from the second list.

3. Enter the function declaration in the Script view.

   For the syntax to use, see the section called “Declaring external functions” in PowerScript Reference or the examples below.

4. Save the object.

   PowerBuilder compiles the declaration. If there are syntax errors, an error window opens, and you must correct the errors before PowerBuilder can save the declaration.

To access context information:

1. Declare an instance or global variable of type ContextInformation:

   ContextInformation icxinfo_base

2. Create the context information service by calling the GetContextService function:

   this.GetContextService("ContextInformation", &
      icxinfo_base)

3. 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

To access environment variables:

1. 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[]

2. Create the context information service by calling the GetContextService function:

   this.GetContextService("Keyword", icxk_base)

3. 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)

4. 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])

To hyperlink to a URL:

1. Declare an instance or global variable of type Inet:

   Inet  iinet_base

2. Create the Internet service by calling the GetContextService function:

   THIS.GetContextService("Inet", iinet_base)

3. Call the HyperLinkToURL function, passing the URL of the page to display when the browser starts:

   iinet_base.HyperlinkToURL  &
      ("http://www.appeon.com")

To perform an HTTP Get:

1. 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

2. Create the Internet service by calling the GetContextService function:

   THIS.GetContextService("Internet", iinet_base)

3. Create an instance of the descendant InternetResult object:

   iir_msgbox = CREATE n_ir_msgbox

4. 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.

To perform an HTTP Post:

1. 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

2. Create the Internet service by calling the GetContextService function:

   THIS.GetContextService("Internet", iinet_base)

3. Create an instance of the descendant InternetResult object:

   iir_msgbox = CREATE n_ir_msgbox

4. 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"

5. 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.

To implement a descendant InternetResult object:

1. Create a standard class user object of type InternetResult.

2. Declare a new user object function as follows:

   • Name

     InternetData

   • Access

     Public

   • Returns

     Integer

   • Argument name

     Data, passed by value

   • Argument datatype

     Blob

3. 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