| Previous | Contents | Index |
A task definition controls the exchange of information with the user, and the processing of that information against the file or database. Each ACMS task definition is made up of one or more steps. ACMS breaks the work to be accomplished by a task into two types of steps:
In ACMS, a workspace is a buffer used to pass data between the task and processing steps, and between the task and exchange steps.
Task group definitions combine similar tasks of an application that need to share common resources such as workspaces, DECforms forms, and procedure servers.
The application definition describes:
Menu definitions list both tasks and additional menus that a user can select from a menu. For example, the tasks on a menu can include adding new employee records, displaying employee information, and entering labor data.
When you write definitions for ACMS tasks, ACMS automatically stores
the definitions in a CDD dictionary. At run time, the definitions are
represented in binary form in databases defined by ACMS. For example, a
task group definition is represented by a task group database that
contains a binary representation of the task group definition.
11.3 Introduction to Using ACMS with Third-Party Databases
ACMS allows the use of any Compaq or third-party database manager that can be called using 3GL languages that adhere to the OpenVMS Calling Standard (such as COBOL, FORTRAN, and C).
To understand the area of an ACMS application that is affected by use of third-party databases, refer to Figure 11-1. Because ACMS is modular, the execution flow (ACMS task definitions) and display I/O (forms management code) are for the most part similar regardless of whether you use Compaq or third-party databases. The key difference is with the location of a few database statements.
When you write ACMS task definitions that access Rdb databases, you can embed database recovery, transaction setting or rollback, and commit statements within the task definition. When using other third-party databases, these functions must reside in the 3GL procedures that perform database access. Thus, the ACMS application components that are most affected by the use of other third-party databases (that is, other than Rdb) are the 3GL procedures that perform database access (labeled Procedure 1 in the Database I/O portion of Figure 11-1).
Depending on the features and capabilities of a particular third-party
database (other than Rdb), there may be other restrictions. For
example, a particular database may use its own internal data dictionary
to store database metadata, and that metadata cannot be integrated with
the CDD data dictionary (such is the case with Oracle). This manual
points out the key restrictions with Oracle databases; for other
third-party databases (other than Oracle and Rdb), you must look at the
documentation for that database to determine restrictions that might
apply when it interoperates with an ACMS environment.
11.4 How Do You Use ACMS with Oracle?
When using Oracle as a database manager with ACMS, you can use the existing 3GL code that accesses the Oracle database with little modification. The main modification is to cut the Oracle application code into smaller, more focused modules to fit with the ACMS approach to procedure servers. ACMS uses four types of procedures:
A programmer who has been writing 3GL code in an Oracle environment without a TP monitor must group the functions of the code into different servers. In an Oracle database environment, a step procedure might be used to perform database read and write operations; an initialization procedure might be used to make connections to a particular Oracle instance; a termination procedure might close those connections to a particular Oracle instance made by the initialization procedure; and a cancel procedure might perform some type of database clean-up after a user cancels an operation already begun.
Typically, similar read-intensive database modules are gathered into a group of step procedure images, while write-intensive database modules are gathered into a different group of step procedure images. This helps to control database locking contention.
Although the structure of existing 3GL code for an Oracle application needs to be reorganized for ACMS, the 3GL code itself does not need to be modified significantly (if at all). Good server design is one of the crucial steps in writing a powerful ACMS application. The ACMS documentation describes ACMS server design and development in detail.
In addition to making your 3GL code more modular, the following functions must remain in the 3GL procedure: database recovery, transaction setting or rollback, and commit functions. (If you have an existing Oracle application, these functions are probably already in your 3GL procedures.)
There are three methods to access an Oracle database using 3GL code:
When you create 3GL modules, keep in mind that the Oracle Corporation provides precompilers for the following Compaq programming languages:
With an Oracle database, data definitions (metadata) are stored in an internal data dictionary that resides in the database. With ACMS and other layered products, metadata is stored in a central location in CDD and then used by the various layered products. To use an Oracle database with ACMS, you must maintain metadata in both CDD and the Oracle database.
The sample application in Chapter 12 provides code examples (with accompanying descriptions) of 3GL code that accesses an Oracle database using embedded SQL.
This chapter contains parts of a sample application that shows how ACMS, by using Oracle as its database manager, can access third-party databases (other than Rdb). The sample is based on a simple car reservation system used by a fictional company named AVERTZ. The complete AVERTZ application is described in the ACMS documentation set.
The AVERTZ sample application is an example of how transaction processing can solve a business problem. The AVERTZ company has rental offices at many sites in different regions and their clerks need to reserve vehicles at any site in any region. The AVERTZ application consists of functions that allow users to view and update all the data necessary to make automobile rental reservations and maintain information on customers. (A modified subset of AVERTZ has been used in this book. The sample has been modified to exclude two-phase database commit functions, which cannot be used when interoperating with Oracle).
The VR_DISPLAY_SITES_TASK task definition, which is included and
described in this manual, displays site and region information. This
task is called from another task in the application. The
VR_DISPLAY_SITES_TASK task uses a server process to access the Oracle
database and retrieve the regions in the database so that the regions
can be displayed using DECforms. After the user selects a region, the
task calls a server procedure (VR_GET_SITES_PROC, also included and
described in this manual) to access the Oracle database to retrieve
site data, which AVERTZ displays using DECforms. The user then selects
a particular rental site, and the necessary information is passed back
to the calling task, where it is processed further.
12.1 Execution Flow of the Sample Task
Figure 12-1 shows how the task definition in this sample controls the flow of work between the user and the Oracle database.
Figure 12-1 Execution Flow of the Sample Task
The sample application is comprised of over 40 separate pieces of code. Although at first glance this might seem like a lot of code, remember that ACMS code is very modular, and these modules contain relatively small amounts of code. This modularity allows the reuse of modules as building blocks when creating other applications.
The following AVERTZ modules are described in this manual:
The code for these files is contained in the following sections, along
with an explanation of what is happening in each file.
12.1.1 Task Definition
Example 12-1 shows the ACMS task definition (VR_DISPLAY_SITES_TASK) that uses exchange steps to display the region and site data, and collects the user's selection of a particular region and a particular site. This task definition coordinates all the steps shown in the task definition in Figure 12-1 (labeled execution flow). The task uses processing steps to call COBOL procedures, which perform the database I/O to the Oracle database and move data between workspaces.
Table 12-1 describes the coding in the VR_DISPLAY_SITES_TASK task definition in more detail.
| Example 12-1 VR_DISPLAY_SITES_TASK Task Definition |
|---|
REPLACE TASK VR_DISPLAY_SITES_TASK [TSK1]
WORKSPACES ARE VR_CONTROL_WKSP, [TSK2]
VR_RE_ARRAY_WKSP,
VR_SI_ARRAY_WKSP,
VR_SITES_WKSP,
VR_MSG_WKSP;
TASK ARGUMENTS ARE VR_CONTROL_WKSP WITH ACCESS READ, [TSK3]
VR_SITES_WKSP WITH ACCESS MODIFY,
VR_MSG_WKSP WITH ACCESS MODIFY;
DEFAULT SERVER IS VR_SERVER; [TSK4]
DEFAULT FORM IS VR_DISPLAY_SITES_FORM; [TSK5]
LOCAL; [TSK6]
BLOCK WORK WITH FORM I/O IS [TSK7]
IF (VR_CONTROL_WKSP.CTRL_KEY = " FREG") THEN
BLOCK WORK IS
GET_REGIONS:
PROCESSING WORK IS [TSK8]
CALL VR_GET_REGIONS_PROC USING VR_RE_ARRAY_WKSP;
ACTION IS [TSK9]
CONTROL FIELD ACMS$T_SEVERITY_LEVEL
"S" : GOTO STEP SELECT_REGION;
"W" : MOVE VR$_RERECNOTFND TO VR_MSG_WKSP.STATUS,
"W" TO VR_MSG_WKSP.SEVERITY_LEVEL;
EXIT TASK;
NOMATCH : MOVE VR$_DB_FATAL TO VR_MSG_WKSP.STATUS,
"F" TO VR_MSG_WKSP.SEVERITY_LEVEL;
EXIT TASK;
END CONTROL FIELD;
SELECT_REGION:
EXCHANGE WORK IS [TSK10]
TRANSCEIVE RECORD RE_ARRAY_FORM_REC, RE_ARRAY_FORM_REC
IN VR_DISPLAY_SITES_FORM
SENDING VR_RE_ARRAY_WKSP
RECEIVING VR_RE_ARRAY_WKSP
WITH RECEIVE CONTROL VR_CONTROL_WKSP;
ACTION IS [TSK11]
CONTROL FIELD IS VR_CONTROL_WKSP.CTRL_KEY
" FQUT" : MOVE VR$_RERECNOTFND TO VR_MSG_WKSP.STATUS,
"W" TO VR_MSG_WKSP.SEVERITY_LEVEL;
EXIT TASK;
END CONTROL FIELD;
MOVE_REGION:
PROCESSING WORK IS [TSK12]
CALL VR_MOVE_RE_PROC USING VR_RE_ARRAY_WKSP, VR_SITES_WKSP;
ACTION IS [TSK13]
CONTROL FIELD IS ACMS$T_STATUS_TYPE
"B" : CANCEL TASK RETURNING ACMS$L_STATUS;
END CONTROL FIELD;
END BLOCK WORK;
END IF;
GET_SITES:
PROCESSING WORK IS [TSK14]
CALL VR_GET_SITES_PROC USING VR_SITES_WKSP,VR_SI_ARRAY_WKSP;
ACTION IS [TSK15]
CONTROL FIELD ACMS$T_SEVERITY_LEVEL
"S" : GOTO STEP SELECT_SITE;
"W" : MOVE VR$_SIRECNOTFND TO VR_MSG_WKSP.STATUS,
"W" TO VR_MSG_WKSP.SEVERITY_LEVEL;
EXIT TASK;
NOMATCH : MOVE VR$_DB_FATAL TO VR_MSG_WKSP.STATUS,
"F" TO VR_MSG_WKSP.SEVERITY_LEVEL;
EXIT TASK;
END CONTROL FIELD;
SELECT_SITE:
EXCHANGE WORK IS [TSK16]
TRANSCEIVE RECORD SI_ARRAY_FORM_REC,SI_ARRAY_FORM_REC
IN VR_DISPLAY_SITES_FORM
SENDING VR_SI_ARRAY_WKSP
RECEIVING VR_SI_ARRAY_WKSP
WITH RECEIVE CONTROL VR_CONTROL_WKSP;
ACTION IS [TSK17]
CONTROL FIELD IS VR_CONTROL_WKSP.CTRL_KEY
" FQUT": MOVE VR$_SIRECNOTFND TO VR_MSG_WKSP.STATUS,
"W" TO VR_MSG_WKSP.SEVERITY_LEVEL;
EXIT TASK;
END CONTROL FIELD;
MOVE_SITE:
PROCESSING WORK IS [TSK18]
CALL VR_MOVE_SI_PROC USING VR_SI_ARRAY_WKSP,VR_SITES_WKSP;
ACTION IS [TSK19]
CONTROL FIELD IS ACMS$T_STATUS_TYPE
"G" : MOVE "S" TO VR_MSG_WKSP.SEVERITY_LEVEL;
EXIT TASK;
"B" : CANCEL TASK RETURNING ACMS$L_STATUS;
END CONTROL FIELD;
END BLOCK;
END DEFINITION;
|
| Callout | Description |
|---|---|
| [TSK1] | Replaces an old CDD dictionary task definition with the current task definition or creates a new definition if one does not already exist. Section 12.4 discusses the role of the CDD dictionary. |
| [TSK2] | Names one or more workspaces to which the task needs access. Workspaces are buffers used to pass data between steps in a task, between a task and a procedure, between a task and a form, and between two or more tasks. |
| [TSK3] | Defines the workspaces that are used to pass data, with the type of access that VR_DISPLAY_SITES_TASK has to them. (Definitions are here because this task is called from another task.) |
| [TSK4] | Names a default server image in which to run the procedures. If this is not specified, the server must be named at each call to a COBOL routine. |
| [TSK5] | Names a default form to be used in the exchange steps. If this is not specified, the form name must be specified with each TRANSCEIVE call in this task. |
| [TSK6] | Specifies that this task can be run only when called from another task. (You cannot select this task to run independently from a menu.) |
| [TSK7] | Groups multiple steps as a logical unit between the BLOCK WORK and END BLOCK WORK clauses. (In this example, the block consists of two EXCHANGE steps and four PROCESSING steps.) FORM I/O is a block phrase indicating that the EXCHANGE steps use DECforms for I/O with the user. |
| [TSK8] | Calls the COBOL procedure VR_GET_REGIONS_PROC within a PROCESSING step. The COBOL procedure performs the Oracle database inquiry and returns the region records to the ACMS task using the VR_RE_ARRAY_WKSP workspace. |
| [TSK9] | Handles potential errors that are returned from VR_GET_REGIONS_PROC. |
| [TSK10] | Calls the DECforms form VR_DISPLAY_SITES_FORM within an EXCHANGE step. DECforms uses the VR_DISPLAY_SITES_FORM to format and display all of the regions on the ACMS user's terminal. The user can also select a particular region at this point. |
| [TSK11] | Handles potential errors that are returned from the DECforms session. |
| [TSK12] | Calls the COBOL procedure VR_MOVE_RE_PROC within a PROCESSING step. The COBOL procedure moves data between workspaces. |
| [TSK13] | Handles potential errors that are returned from VR_MOVE_RE_PROC. |
| [TSK14] | Calls the COBOL procedure VR_GET_SITES_PROC within a PROCESSING step. The COBOL procedure performs the Oracle database inquiry and returns the site records to the ACMS task using the VR_SI_ARRAY_WKSP workspace. |
| [TSK15] | Handles potential errors that are returned from VR_GET_SITES_PROC. |
| [TSK16] | Calls the DECforms form VR_DISPLAY_SITES_FORM within an EXCHANGE step. DECforms uses the VR_DISPLAY_SITES_FORM to format and display all the sites on the ACMS user's terminal. The user can select a particular site at this point. |
| [TSK17] | Handles potential errors that are returned from the DECforms session. |
| [TSK18] | Calls the COBOL procedure VR_MOVE_RE_PROC within a PROCESSING step. The COBOL procedure moves data between workspaces. |
| [TSK19] | Handles potential errors that are returned from VR_MOVE_SI_PROC. |
Keep the following in mind so that your task definition code is interoperable:
As of ACMS Version 3.2, these statements (SQL RECOVERY, COMMIT and ROLLBACK) are considered declining features of ACMS TDL anyway.
| Previous | Next | Contents | Index |