HP OpenVMS Systems Documentation

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.

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.

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.

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.

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.

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.

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.

        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.

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:

• You can use all the Oracle tools, such as SQL*Plus, SQL*Forms and SQL*Report, while an ACMS and Oracle application is running.
• You can use Compaq CASE tools such as DECset (a collection of code editing, management, testing, and analysis tools) regardless of whether a Compaq or a third-party database is used. You can even create custom LSE editing templates to handle Oracle-specific SQL syntax.
• The combination of ACMS and Oracle with the use of SQL*Net allows an online TP application to access Oracle data on other platforms. In addition, the use of Oracle's SQL*Connect gateways provides links to non-Oracle data sources on other platforms.

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:

• Why would you want to use Compaq and ACMS?
• How does APPC/LU6.2 work as a gateway between an ACMS application and an IBM system?
• What are the basic concepts of ACMS and APPC/LU6.2?

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:

• Use the appropriately sized (and, therefore, appropriately priced) computer system for different business needs. Compaq's ACMS software runs on all OpenVMS machines, from the smallest desktop to the largest mainframe. Every one of these machines can interoperate with IBM CICS applications.
• Integrate your existing systems into the ACMS environment to protect your current investment. In addition to being able to connect with IBM CICS applications, the Compaq TP Desktop Connector (formerly ACMS Desktop) product allows DOS, Macintosh, SCO UNIX, and ULTRIX systems to tie into the ACMS environment using a client/server computing approach.
• Move computing to the right location. With ACMS, you can either keep your business data in a central location or scatter it throughout your corporation.

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:

• A task definition describes, in steps, the work to be accomplished in the task. For example, a task can collect information from a user and call a procedure to store the information in a file or database.
• A task group definition specifies similar tasks for control purposes and defines resources common to all tasks in the group.
• An application definition describes the environment and control characteristics of tasks and task groups.
• A menu definition describes how users access tasks in one or more applications.

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:

• Exchange steps usually interact with the Form Manager to handle forms I/O (that is, the exchange of information between the task and the user). An exchange step can interact with DECforms or TDMS forms, or interface with other devices using the ACMS Request Interface or the ACMS Systems Interface for communicating with nonstandard devices. Figure 13-1 illustrates an execution flow with two exchange steps.
• Processing steps call step procedures (user-written subroutines) to handle computations and interactions with databases or files, typically using procedures written in a high-level programming language (any language adhering to the OpenVMS Calling Standard). ACMS uses two types of servers: procedure servers for executing a procedure, and DCL servers for invoking images or DCL commands. Figure 13-1 illustrates an execution flow with one processing step.
  A server process may perform an initialization routine of common work when the server is started, rather than each time a task is selected. ACMS manages pools of servers to save on process creation and image activation.
  Servers are single-threaded and serially reusable. A single server process can be called by many different ACMS tasks in a serial fashion. Once a call is complete, the server is then available to be called by another ACMS task. Reusable servers in a single process means that the performance in the processing of your transactions is greatly enhanced.
  When ACMS starts a processing step, it allocates a procedure server process to a task to execute the procedure in that step. This single-threaded process remains allocated to the task for the duration of one or more processing 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:

• Task groups that belong to an application
• Characteristics that control the tasks, such as security restrictions on which users can select a particular task
• Servers, such as the number of server processes that can be active at the same time
• Application characteristics, such as whether application activity is recorded in the audit trail log

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:

• Establish LU6.2 sessions
• Set up conversations between transaction programs
• Send and receive data
• Support mapped and basic conversations
• Confirm data exchange

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:

• DECnet/SNA Gateway synchronous transport (ST), which connects the Compaq system physically to an IBM Systems Network Architecture (SNA) network. Once on the SNA network, ACMS can connect to a myriad of host IBM mainframes. The one or more IBM mainframes are connected to the same SNA network by a front-end processor (FEP).
• DECnet/SNA Gateway channel transport (CT), which connects the Compaq system directly to an IBM mainframe by way of a hardwired channel port on the IBM host.

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.