begingroup

The begingroup statement indicates the beginning of a group of procedures that will be processed as a single entity. This statement allows you to define the name of the group and several attributes that will be used to place this group in the appropriate process queue, either locally or at a process server.

Syntax

begingroup group_name {with load factor factor} {using service service_name} {with priority value} {queue at time on date} {recur every interval [minutes|hours|days|weeks|months|years]} {notify procedure} {groupdone procedure} {deletable deletable_boolean} assign to group_ID

Parameters

• group_name – A string containing the name for the group being created. This name will appear in the Process Monitor window when the group is running.

• with load factor factor – An integer value used to measure the relative amount of work required to complete this process group. For example, if you have a process group that prints two simple reports, it will require less work (therefore putting less of a load on the process server) than a process group printing seven long and complex reports. Valid values for the factor parameter are in the range 1 to 1000, with 1000 representing the heaviest load on the process server.

• using service service_name – Specifies a predefined set of process servers that this process group could be sent to. If this parameter isn’t included, the group will be processed locally. Which server it is sent to depends upon the size, priority and load factor of the current process group and the process groups in the process queue at each process server in the named service. Since this parameter deals with processes that are to be sent to a process server, it should be used for only client/server applications.

• with priority value – An integer that assigns a level of priority to the tasks this process group will perform. Valid values for the value parameter are in the range 1 to 100, with 1 having the highest priority.

• queue at time on date – Assigns a date and time when the process group will be sent to the appropriate process queue. There is no guarantee that the group will begin processing at the specified time, as other process groups with higher priority levels may already be in that queue. If this parameter isn’t included, or the time and date values are empty, the group will begin processing immediately.

• recur every interval [minutes | hours | days | weeks | months | years] – A frequency with which you want this process sent to a process queue. The interval specified must be an integer in the range of 1 to 10000.

• notify procedure – A string containing the name of a procedure on the client to be called when the process group has run to completion. This allows you to notify the user that this process group’s task has been completed.

• groupdone procedure – A string containing the name of a procedure to be called when the process group has run to completion. The procedure will be executed where the group was processed. For example, if the group was processed remotely on a process server, the procedure will be executed on the process server. If the group was processed locally, the procedure will be executed locally.

• deletable deletable_boolean – A flag specifying whether the process group can be deleted from a process queue. True indicates the group can be deleted, while false indicates it can’t.

• assign to group_ID – A long integer variable to which the ID generated by Dexterity for this group is assigned. The group_ID uniquely identifies the process group.

Comments

This statement can be used when processing shouldn’t be interrupted for a group of procedures, such as posting procedures. All procedures in a group defined by begingroup will be treated as a single item, and placed in the client’s process queue (if the using service service_name parameter isn’t used) or the Process Server process queue (if the using service service_name parameter is used and the procedures are called using call remote statements).

The process group’s group_name will appear in the Process Monitor window, followed by the number of procedures in the process group.

As processes are added to a process queue, they are inserted into the queue based upon their priority value. For example, if a process group of priority 50 is added to a queue, it will be inserted into the queue before any groups of priority 51 or higher, and after any of priority 50 or lower. Active process groups always run to completion and can’t be interrupted by higher-priority groups.

If you use the notify procedure or groupdone procedure parameters, the named procedure must contain three in parameters. The first parameter must be a string to accommodate the name of the process group. The second parameter must be a long integer to accommodate the group ID that is assigned by the begingroup statement. The third parameter also must be a long integer to accommodate the completion status of the process group.

The following constants indicate the completion status:

Documentation Feedback

---