Compaq ACMS for OpenVMS
Writing Server Procedures


Previous Contents Index

12.3.1 Initialization Procedure

Example 12-6 is the server initialization procedure (VR_INIT) written in COBOL. The server initialization procedure performs work that must be done before any step procedure executes. The initialization procedure is executed only once before the server becomes available. In this case, the initial connection is made to the Oracle database.

Table 12-6 describes the coding in the INIT_EMPL_INFO initialization procedure in more detail.

Example 12-6 VR_INIT Initialization Procedure

IDENTIFICATION DIVISION. 
PROGRAM-ID. VR-INIT. 
 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER.        VAX-11. 
OBJECT-COMPUTER.        VAX-11. 
 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
 
        EXEC SQL INCLUDE                                               [INI1]
            AVERTZ_ORACLE_DIR:SQLCA.CBT 
        END-EXEC. 
 
        EXEC SQL                                                       [INI2]
                BEGIN DECLARE SECTION 
        END-EXEC. 
 
01 CONNECT-DATA. 
   02 USERID               PIC X(3) VALUE "SYS". 
   02 PASSWORD             PIC X(3) VALUE "B52". 
 
        EXEC SQL 
                END DECLARE SECTION 
        END-EXEC. 
 
PROCEDURE DIVISION. 
MAIN SECTION. 
 
000-OPEN_DB. 
 
        EXEC SQL                                                       [INI3]
            CONNECT :USERID IDENTIFIED BY :PASSWORD 
        END-EXEC. 
 
100-EXIT-PROGRAM. 
       
       EXIT PROGRAM. 

Table 12-6 Description of Code for VR_INIT Initialization Procedure
Callout Description
[INI1] Includes the Oracle SQL communications area that is updated every time an SQL statement is executed.
[INI2] Declares the Oracle username and password that the server uses to connect to the instance of the Oracle database. Instead of hard-coding this security information in the initialization procedure, you can take advantage of the automatic logon feature of Oracle. If the Oracle username is specified as OPS$username, where username is the OpenVMS account that the server is running in, the connect statement can then be "CONNECT :/".
[INI3] Makes the connection to the Oracle database instance.

12.3.2 Termination Procedure

Example 12-7 is the server termination procedure (VR_TERM) written in COBOL. The termination procedure performs any cleanup work that must be done before the procedure server runs down. In this example, the procedure simply disconnects the server from the database.

Table 12-7 describes the coding in the VR_TERM termination procedure in more detail.

Example 12-7 VR_TERM Termination Procedure

IDENTIFICATION DIVISION. 
PROGRAM-ID. VR-TERM. 
 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER.        VAX-11. 
OBJECT-COMPUTER.        VAX-11. 
 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
 
        EXEC SQL                                                       [TRM1]
            INCLUDE AVERTZ_ORACLE_DIR:SQLCA.CBT 
        END-EXEC. 
 
        EXEC SQL                                                       [TRM2]
            BEGIN DECLARE SECTION 
        END-EXEC. 
 
01 CONNECT-DATA. 
        02 USERID               PIC X(3) VALUE "SYS". 
        02 PASSWORD             PIC X(3) VALUE "B52". 
 
        EXEC SQL 
            END DECLARE SECTION 
        END-EXEC. 
 
PROCEDURE DIVISION. 
MAIN SECTION. 
 
000-CLOSE_DB. 
 
        EXEC SQL                                                       [TRM3]
            COMMIT 
        END-EXEC. 
 
100-EXIT-PROGRAM. 
        EXIT PROGRAM. 

Table 12-7 Description of Code for VR_TERM Termination Procedure
Callout Description
[TRM1] Includes the Oracle SQL communications area that is updated every time an SQL statement is executed.
[TRM2] Declares the Oracle username and password.
[TRM3] The connection to the Oracle database instance is severed.

12.4 Field and Record Definitions

Data dictionaries contain metadata (descriptions of data, not the data itself) in the form of dictionary definitions. The most commonly used dictionary definitions are fields and records.

A field definition describes the data that can be stored in a specific field in your application. Field definitions typically include information such as data type and size. In this sample, site fields are defined.

A record definition consists of a grouping of field definitions. This sample defines a record named VR_SITES_WKSP, which contains a group of field definitions corresponding to the sites.

In an ACMS application that is written using a native Compaq database manager, the record definitions that are stored in the CDD data dictionary are normally used as ACMS workspace definitions, 3GL record definitions, DECforms form records definitions and database definitions. Because an Oracle database has its own internal data dictionary, CDD cannot be used to store Oracle metadata.

Any program variables used in an Oracle SQL statement must be defined within an SQL DECLARE SECTION. You can create a text copy of the record definition in the Oracle database and copy it into the program (using an SQL INCLUDE statement) at time of Oracle precompile. In this scenario, the Oracle database and the ACMS workspaces or 3GL server programs do not share data definitions.

The CDD field definitions in Example 12-8 specify the information on fields used in AVERTZ. In addition to the name, each field definition also includes the data type and size for each field.

Example 12-8 Field Definitions

DEFINE FIELD SITE_ID                DATATYPE SIGNED LONGWORD. 
DEFINE FIELD SITE_NAME              DATATYPE TEXT SIZE 25. 
DEFINE FIELD FIRST_ADDRESS_LINE     DATATYPE TEXT SIZE 25. 
DEFINE FIELD SECOND_ADDRESS_LINE    DATATYPE TEXT SIZE 25. 
DEFINE FIELD CITY                   DATATYPE TEXT SIZE 20. 
DEFINE FIELD REGION_ID              DATATYPE SIGNED LONGWORD. 
DEFINE FIELD COUNTRY_ID             DATATYPE SIGNED LONGWORD. 
DEFINE FIELD POSTAL_CODE            DATATYPE TEXT SIZE IS 10. 
DEFINE FIELD PHONE_NO               DATATYPE TEXT SIZE IS 21. 

AVERTZ uses both records and workspaces. Example 12-9 shows one of the workspace definitions contained in CDD for AVERTZ. This workspace definition can be used in the 3GL procedures if the variables in the record are not referenced in an Oracle SQL statement.

Example 12-9 Record and Workspace Definitions

DEFINE RECORD VR_SITES_WKSP 
 
SITE_ID. 
SITE_NAME. 
FIRST_ADDRESS_LINE. 
SECOND_ADDRESS_LINE. 
CITY. 
REGION_ID. 
COUNTRY_ID. 
POSTAL_CODE. 
PHONE_NO. 
 
END RECORD. 

If the variables in the record are referenced in an Oracle SQL statement in the COBOL procedure, the third definition, shown in Example 12-10, is necessary. All variables that are used in an Oracle SQL statement must be included in a DECLARE SECTION.

Example 12-10 Text Library Record Definition

        EXEC SQL 
                BEGIN DECLARE SECTION 
        END-EXEC. 
 
 01  VR_SITES_WKSP. 
        05  WS_SITE_ID                          PIC S9(9) COMP. 
        05  WS_SITE_NAME                        PIC X(25). 
        05  WS_FIRST_ADDRESS_LINE               PIC X(25). 
        05  WS_SECOND_ADDRESS_LINE              PIC X(25). 
        05  WS_CITY                             PIC X(20). 
        05  WS_REGION_ID                        PIC S9(9) COMP. 
        05  WS_COUNTRY_ID                       PIC S9(9) COMP. 
        05  WS_POSTAL_CODE                      PIC X(10). 
        05  WS_PHONE_NO                         PIC X(21). 
 
        EXEC SQL 
                END DECLARE SECTION 
        END-EXEC. 

12.5 CASE Tools

When you use ACMS with Oracle, you combine the power of the best CASE tools for both environments. Note the following about using CASE tools when you create interoperable ACMS and Oracle applications:


Part 4
Interoperability with IBM LU6.2 and CICS

This part of the manual describes how Compaq ACMS for OpenVMS transaction processing (TP) software works with APPC/LU6.2 programming interface software (developed by Digital Equipment Corporation) to communicate with an IBM® CICS® application on an IBM system.


Chapter 13
Overview of ACMS and APPC/LU6.2

This chapter provides a high-level technical discussion of how you can use APPC/LU6.2 as a gateway between a Compaq ACMS for OpenVMS application (Compaq's transaction processing system) and an IBM system, and specifically answers the following questions:

13.1 Why Use Compaq and ACMS?

When you read articles and business school case studies on companies that remain competitive year after year, decade after decade, you typically find a common denominator for those companies: they remained flexible enough to change the way they did business to suit the current business environment. If information is critical to the operation of your business, do you also need that same advantage of flexibility?

Compaq offers you computing solutions that fit for today and for the future as well. Because Compaq is the premier vendor in interoperability and networking, flexibility means the ability to:

With Compaq, flexibility means the choice is yours!

13.2 Introduction to Developing ACMS Applications

An ACMS application consists of a set of tasks that relate to the functions of a business. A task is the unit of work that a user selects from an ACMS menu. Each task usually comprises a sequence of steps that perform this unit of work. You use the ACMS task definition language (TDL) to define tasks.

Figure 13-1 illustrates the basic principles of the ACMS TDL used to write a task definition.

The task definition specifies an interface to the presentation service (forms management system) for communication with a terminal or other device. The task definition also specifies an interface to a procedure server for executing procedures (user-written subroutines) that handle database I/O and computational work.

Figure 13-1 Execution Flow of an ACMS Task Definition


The semantics of the ACMS task definition language are based on a call and return model. The task definition performs calls to the presentation service in exchange steps, and to the procedure server in processing steps. The presentation service and procedure server perform a function and return control to the task definition. Upon return of control to the task definition, subsequent parts of a step can evaluate the results of the call and, if necessary, handle any error conditions.

In Figure 13-1, for example:

  1. In the first exchange step, the task definition calls the presentation service to display a form on the terminal screen (for example, a form to add a new employee record to a database). When the terminal user finishes filling in the form, the user presses a specified key (or keys) that returns the input data to the task definition.
  2. In the processing step, the task definition then calls Procedure 1 in the procedure server to write that input data to the database. Procedure 1 then returns its results (either success or failure). If Procedure 1 succeeds, the task ends with a success status. If Procedure 1 fails to write to the database, the task continues executing at step 3.
  3. In the second exchange step, the task definition calls the presentation service to send an error message to the terminal screen (for example, that the employee number of the new record duplicates an existing employee number). The presentation service then returns control to step 3, which ends the task.

By keeping exchange and processing steps as distinct steps within an ACMS task, ACMS allows for the separation of forms (end-user interaction) from function (database access, computation, and execution control). This means that you can easily distribute end-user processing while maintaining centralized data control.

13.2.1 Writing ACMS Definitions

The ACMS task definition language allows you to write an ACMS definition as a series of simple, English-like statements. The four types of ACMS definitions are:

You build the task, task group, and application definitions into binary files that run as an application under the control of the ACMS run-time environment. You build a menu definition into a binary file that is not necessarily tied to a single application.

Figure 13-2 illustrates the ACMS development components for a simple ACMS application with two tasks (for example, one to add a new employee record to a database, and one to update an existing employee record).

Figure 13-2 ACMS Application Components


Figure 13-2 does not show that there can be more than one task group definition specified for a single application. Also, more than one menu definition can specify tasks that point to the same application. Conversely, a single menu definition can specify tasks in different applications.

Because ACMS applications are modular, you develop each part of an application independently. Built-in modular design based on English-like syntax statements means that ACMS applications are easy to structure and easy to maintain. Furthermore, modularity means that you can easily update an application module without affecting the entire application.

13.2.2 Composition of ACMS Definitions

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.

Chapter 14 provides code examples (with accompanying descriptions) of the different components of an ACMS application.

13.3 Introduction to Using the APPC/LU6.2 Programming Interface

Logical Unit 6.2 is a general purpose architecture that enables IBM products to communicate with one another. Unlike other IBM LUs, which are designed with specific products in mind, LU6.2 has general function as the goal (that is, a common LU for all products).

The LU6.2 architecture defines a set of protocols. To communicate with one another, products (such as Compaq's APPC/LU6.2 Programming Interface) must implement LU6.2 according to these protocols.

Communication using LU6.2 is analogous in function to the DECnet task-to-task communication over a DECnet logical link. As with DECnet, communication between transaction programs using LU6.2 is transparent. You can develop applications that move data through a DECnet network to a remote IBM host transaction program without requiring your programmers to know the details of SNA.

LU6.2 transaction programs exchange information by means of a conversation, which is a temporary logical path established between two cooperating transaction programs. As in DECnet task-to-task communication, transaction programs must cooperate during the transaction process. For instance, when one transaction program issues a command to send data, the other transaction program must issue a command to receive the data. In cooperating transaction programs (such as ACMS and CICS), you can make calls to the APPC/LU6.2 Programming Interface procedures to:

Before transaction programs can exchange messages, their LUs must first establish a logical connection or session. A session is a long-term logical connection that permits communication between two logical units (such as between ACMS and CICS). A conversation is a short-term logical connection that lasts only for the duration of one complete transaction. ACMS establishes both sessions and conversations by using explicit calls to APPC/LU6.2 procedures.

Chapter 14 provides code examples (with accompanying descriptions) of how these APPC/LU6.2 Programming Interface calls are made.

13.4 How Do You Connect ACMS with IBM CICS Systems?

Using the APPC/LU6.2 Programming Interface, you can develop ACMS applications that exchange messages with remote IBM host transaction programs (such as CICS). Figure 13-3 shows how ACMS works with APPC/LU6.2 to connect to an IBM mainframe.

Figure 13-3 How ACMS and APPC/LU6.2 Connect to an IBM Machine


Figure 13-3 shows a Compaq server node running ACMS (with APPC/LU6.2 running on the same Compaq system). The Compaq computer can be attached either to Compaq's proprietary network DECnet, or to an Open Systems Interconnection (OSI) network.

As shown in Figure 13-3, a Compaq node running ACMS software can connect to an IBM system by two physical paths:

Once the hardware connection is established, ACMS works together with APPC/LU6.2 to start a CICS transaction. Chapter 14 describes the code for an example of an ACMS application making a request to a CICS application for data stored in an IBM database.


Previous Next Contents Index