scope

Declares a scope block, which specifies the data that is to be included in a DSP request-response exchange for the current trigger or operation. 

public|partnerweb
{scope
  {input}
  {output}
  {operationInstanceName.OperationName| CallbackFunction().OperationName
  {operationInstanceNameN.OperationNameN| CallbackFunction().OperationName} } …*
{endscope}}

Arguments

Arguments
Parameter Description

partner

See web

scope / endscope

 Define the beginning and end of the scope declaration; If no scope block is defined, the scope is assumed to be both input and output scope.
input Include all component data (with the exception of properties) in the request sent from browser to server.
output Include all component data (including properties) in the response sent back from the server to browser.
operation Use the scope definition of one or more specified operations. This enables you to include data from other DSPs. The instance name can be declared statically or dynamically:
  • Static declaration: operationInstanceName.OperationName
  • Dynamic declaration: operationCallbackFunction.OperationName
Note:  An exec operation cannot be included in a scope operation definition.
InstanceName Name of a DSP component instance that holds the definition for the requested operation; maximum length of 16 bytes.
OperationName Name of an operation that is part of the specified component instance.
CallbackFunction Name of a weboperation (if the scope declaration is in an operation or in the exec operation), or webtrigger (if the scope declaration is in a trigger) that returns a list of DSP instances at runtime.

Return Values

None

Use

Use in Dynamic Server Page components.

Allowed only in the following locations:

  • exec operation
  • Any operation, whether executed on the server (operation) or on the client (weboperation)
  • Any field trigger that is valid for the assigned widget, including client-side triggers (webtrigger). For valid triggers, see the specific widget description.

Description

The scope declaration specifies the data that is to be included in a DSP request-response exchange. If no explicit scope declaration is specified, the default is used, which is:

  • All component data, with the exception of properties, is sent from the browser to the server
  • All component data, including properties, is returned from the server to the browser. Data included in the output scope is blocked from being updated by other operations or triggers until the response has been received and the page updated.

The scope block is used by the browser to select the input for a specified operation, or to block data expected in the response, to ensure that data on the client and server are kept synchronized.

Client-side operations and triggers defined with webtrigger and weboperation are subject to the same scope rules as server-side operations and triggers. This means that if the JavaScript API is used to call a client-side operation, execution of the operation may be postponed if its input or output is blocked.

Qualifying the Scope

If the web statement is omitted, the operation is not available from the web. This ensures that Uniface components are protected from unauthorized calls or attacks.

Setting the qualifier to public web, makes it possible for a web browser to execute the trigger or operation in which the scope statement occurs. This obviously has security risks associated with it, so you need to use it appropriately. Typically, you can use it in the detail and OnChange triggers to accept some kind of user interaction, but you would not use it in an operation, especially one that stores data.

Input Scope

The following code sets the input scope of the showDetails operation called in the Detail trigger of a field, then activates the operation. When the user clicks on this field in the browser, the showDetails operation on another server page is called. 

trigger detail; of Picture field
public web
scope
   input
   operation MUSICDETAILS.ShowDetails ; where MUSICDETAILS is the instance name
endscope
; newinstance "DETAILS", "MUSICDETAILS" ; if instance != component

activate "MUSICDETAILS".ShowDetails(ITEMID)
end; detail

The output scope of the called operation blocks the data on the browser until the response containing that data is sent.

operation ShowDetails
   partner web
   scope
      output
   endscope

   params
      string pItemId : IN
   endparams

   ITEMID.ITEMDETAILS/init = pItemId
   retrieve/e "ITEMDETAILS"
end

Output Scope

The following example for a Clear button clears the contents of the DSP. To prevent the current contents of the DSP from being sent to the browser, which creates extra network traffic for data that is being discarded, only the output scope is defined. After a clear command, Uniface returns an empty occurrence.

;BTN_CLEAR DETAIL Trigger
public web
scope
  output
endscope

clear/e "PERSON"
if ($status < 0)
  webmessage/error "Clear failed ($status = %%$status%%%)"
endif
return 0

Dynamic Scope

Dynamic scoping makes it possible to determine the scope of an operation or trigger at runtime, instead of during development.

In a dynamic web application, components may be created in response to user choices, and each instance needs to be uniquely named. The available instances and their names are not known ahead of time, so they cannot be statically included in the scope definition using operationInstanceName.OperationName.

Instead, you can use a callback function that returns a list of dynamically-created DSP instances to be included in the scope of the operation or trigger. For example:

scope
  operation myCallbackFunction().myOperation 
endscope

The callback function is executed by the Javascript API to determine the scope of the operation or trigger before it is executed. It does not modify the input or output scope—the operation or trigger in which the callback function is used will always be blocked by its callback function.

For more information, see Dynamic Scope .

Dynamic Scope in Operations

The following example shows an operation containing a mixture of static and dynamic scope declarations:

operation createOrder
public web
scope
   input
   output
   operation I1.create               ;static declaration. I1 is an instance name.
   operation getInstances().create   ;dynamic declaration.
endscope
...
end

Because createOrder is an operation, the getInstances callback function must be a weboperation:

weboperation getInstances
javascript
   var instanceName = this.getName();
   return [instanceName + "01", instanceName + "02"]
endjavascript

The JavaScript context of the callback function is identical to the context of the createOrder operation, so the JavaScript keyword this refers to the DSP instance of the createOrder operation.

Dynamic Scope in Triggers

The following example shows a dynamic scope declaration in a Detail trigger:

; Detail trigger
public web
scope
   input
   output
   operation getModifiedInstances().store
endscope

...

The getModifiedInstanceswebtrigger callback retrieves a list of instances from a field named "INSTANCES".

webtrigger getModifiedInstances
javascript
   var occ = this.getParent();
   var field = occ.getField("INSTANCES");
   return [field.getValue()];
endjavascript
end
Version Change
9.4.01 Introduced
9.6.01 Added operationCallbackFunction().OperationName for dynamic scoping

Related Topics