# Compaq ACMS for OpenVMS
Writing Server Procedures

Previous | Contents | Index

## 14.1.4 Display Form Definition

Example 14-4 shows the DECforms form definition (EMPLOYEE_INFO_FORM) that defines the characteristics for displaying the employee record on the user's terminal. The ACMS task uses this form to display the various fields of information in the employee record on the ACMS user's terminal.

This code is not hand-generated, but rather is generated by the DECforms Forms Development Environment, an easy-to-use interface for forms generation. Because this coding is computer-generated (programmers do not need to generate this code), there is no detailed explanation of the code following the example.

Example 14-4 EMPLOYEE_INFO_FORM Form Definition

       Form EMPLOYEE_INFO_FORM

        Form Data
            EMPL_NUMBER Character (6)
            EMPL_NAME Character (20)
            EMPL_STREET_ADDRESS Character (20)
            EMPL_PHONE Character (8)
            EMPL_DATE Character (8)
            EMPL_AMOUNT Character (8)
            EMPL_COMMENT Character (9)
        End Data

        Form Record EMPLOYEE_INFO_RECORD
        copy
            employee_info_record from dictionary
        end copy
        end record

        Form Record CONTROL_WORKSPACE
            ERROR_STATUS_FIELD Character (4)
            MESSAGEPANEL Character (80)
        End record

       /************
        *VT Layout *
        ************/

        Layout VT_LAYOUT
            Device
                Terminal
                    Type %VT100
            End Device
            Size 24 Lines by 80 Columns

            Function QUIT_KEY
                Is %PF4
            End Function

            Function Response QUIT_KEY
                Remove All
                Return
                    " FQUT"
            End Response

            Disable Response
                Request Exit Response
                    Remove All
                End Response
            End Response

            Receive Response EMPLOYEE_INFO_RECORD
                    Reset All
                    Display EMPLOYEE_INFO_PANEL
                    Activate Panel EMPLOYEE_INFO_PANEL
            End Response

            Send Response EMPLOYEE_INFO_RECORD
                Display EMPLOYEE_INFO_PANEL
                Activate Panel EMPLOYEE_INFO_PANEL
                Position to Field EMPL_NAME on EMPLOYEE_INFO_PANEL
            End Response

            Send Response CONTROL_WORKSPACE
                Activate Wait
                Signal
            End Response

       /*****************************
        *Employee Info Panel Layout *
        *****************************/

            Panel EMPLOYEE_INFO_PANEL

                Remove

                Literal Text
                    Line 1
                    Column 13
                    Value "EMPLOYEE INFORMATION RECEIVED FROM THE IBM APPLICATION"
                End Literal

                Literal Text
                    Line 5
                    Column 1
                    Value "Employee number:"
                End Literal

                Literal Text
                    Line 7
                    Column 1
                    Value "Employee name:"
                End Literal

                Literal Text
                    Line 8
                    Column 1
                    Value "Address:"
                End Literal

                Literal Text
                    Line 9
                    Column 1
                    Value "Phone:"
                End Literal

                Literal Text
                    Line 10
                    Column 1
                    Value "Hire Date:"
                End Literal

                Literal Text
                    Line 11
                    Column 1
                    Value "Amount:"
                End Literal

                Literal Text
                    Line 12
                    Column 1
                    Value "Comments:"
                End Literal

                Literal Text
                    Line 16
                    Column 1
                    Value "Press PF4 to continue."
                End Literal

                Field EMPL_NUMBER
                    Line 5
                    Column 19
                    Output Picture X(6)
                End Field

                Field EMPL_NAME
                    Line 7
                    Column 19
                    Output Picture X(20)
                End Field

                Field EMPL_STREET_ADDRESS
                    Line 8
                    Column 19
                    Output Picture X(20)
                End Field

                Field EMPL_PHONE
                    Line 9
                    Column 19
                    Output Picture X(8)
                End Field

                Field EMPL_DATE
                    Line 10
                    Column 19
                    Output Picture X(8)
                End Field

                Field EMPL_AMOUNT
                    Line 11
                    Column 19
                    Output Picture X(8)
                End Field

                Field EMPL_COMMENT
                    Line 12
                    Column 19
                    Output Picture X(9)
                End Field

            End Panel

        End Layout
    End Form

# 14.2 Application, Task Group, and Menu Definitions

This section describes the code that:

- Sets the environment and control characteristics of tasks and task groups (EMPLOYEE_INFO_APPL_ACMS_APPC application definition)
- Sets the resources required by a task or group of tasks (EMPLOYEE_INFO_TASK_GROUP task definition)
- Displays a list from which terminal users can choose available tasks (EMPLOYEE_INFO_MENU menu definition)

## 14.2.1 Application Definition

Example 14-5 is an ACMS application definition (EMPLOYEE_INFO_APPL_ACMS_APPC) that defines the characteristics for the application, the servers, and the task groups.

Table 14-3 describes the coding in the EMPLOYEE_INFO_APPL_ACMS_APPC application definition in more detail.

Example 14-5 EMPLOYEE_INFO_APPL_ACMS_APPC Application Definition

       REPLACE APPLICATION EMPLOYEE_INFO_APPL_ACMS_APPC                    [APP1]
       AUDIT;
       APPLICATION USERNAME IS EMPLOYEE_EXC;

       SERVER DEFAULTS ARE                                                 [APP2]
        AUDIT;
        USERNAME IS EMPL_SERVER;
        MAXIMUM SERVER PROCESSES IS 1;
        MINIMUM SERVER PROCESSES IS 1;
       END SERVER DEFAULTS;

       TASK DEFAULTS ARE                                                   [APP3]
        AUDIT;
       END TASK DEFAULTS;

       TASK GROUPS ARE                                                     [APP4]
        EMPLOYEE_INFO_TASK_GROUP:
        TASK GROUP FILE IS "ACMS_APPC_FILES:EMPLOYEE_INFO_TASK_GROUP.TDB";
       END TASK GROUPS;
       END DEFINITION;

Table 14-3 Description of Code for EMPLOYEE_INFO_APPL_ACMS_APPC Application Definition
Callout | Description
--- | ---
`[APP1]` | Replaces an old CDD dictionary application definition with the current application definition or creates a new definition if one does not already exist. Section 14.4 discusses the role of the CDD dictionary. The AUDIT clause indicates that application-level activities (such as starting and stopping the application) are noted in the ACMS audit log.
`[APP2]` | Describes the attributes for the procedure server. (The sample procedure server consists of three procedures combined into a single server: the COBOL database inquiry procedure, the initialization procedure, and the termination procedure.) The AUDIT clause indicates that server-level activities (such as the calling of servers, including the time and user name of the caller) are noted in the ACMS audit log.
`[APP3]` | Describes the defaults for each task. The AUDIT clause indicates that task-level activities (such as the calling of tasks, including the time and user name of the caller) are noted in the ACMS audit log.
`[APP4]` | Lists the task groups that are associated with this particular application. Although this sample has a single task and a single task group, ACMS applications often consist of several tasks in each task group, and several task groups in each application.

## 14.2.2 Task Group Definition

Example 14-6 is an ACMS task group definition (EMPLOYEE_INFO_TASK_GROUP). The task group definition specifies:

- DECforms form file information
- Tasks that belong to the group
- Procedures that are in each server
- Workspaces used by the tasks

Table 14-4 describes the coding in the EMPLOYEE_INFO_TASK_GROUP task group definition in more detail.

Example 14-6 EMPLOYEE_INFO_TASK_GROUP Task Group Definition

       REPLACE GROUP EMPLOYEE_INFO_TASK_GROUP                              [GRP1]
         FORM IS EMPLOYEE_INFO_FORM IN "ACMS_APPC_FILES:EMPLOYEE_INFO_FORM"[GRP2]
           WITH NAME EMPLOYEE_INFO_LABEL;
         FORM IS EMPLOYEE_INFO_PROMPT_FORM
           IN "ACMS_APPC_FILES:EMPLOYEE_INFO_PROMPT_FORM"
           WITH NAME EMPLOYEE_INFO_PROMPT_LABEL;
       TASKS ARE                                                           [GRP3]
        EMPLOYEE_INFO_READ_TASK : TASK IS EMPLOYEE_INFO_READ_TASK;
       END TASKS;

       SERVER IS                                                           [GRP4]
        EMPL_SERVER :
           DEFAULT OBJECT FILE IS EMPL_SERVER;
           PROCEDURE SERVER IMAGE IS "ACMS_APPC_FILES:EMPL_SERVER";
           INITIALIZATION PROCEDURE IS INIT_EMPL_INFO;
           TERMINATION PROCEDURE IS TERM_EMPL_INFO;
           PROCEDURES ARE
                    READ_EMPL_INFO;
       END SERVER;

       WORKSPACES ARE                                                      [GRP5]
        EMPLOYEE_INFO_WKSP,
        EMPLOYEE_INFO_WKSP WITH NAME EMPLOYEE_INFO_COMPARE_WKSP,
        QUIT_WORKSPACE,
        CONTROL_WORKSPACE;

       END DEFINITION;

Table 14-4 Description of Code for EMPLOYEE_INFO_TASK_GROUP Task Group Definition
Callout | Description
--- | ---
`[GRP1]` | Replaces an old CDD dictionary task group definition with the current task group definition or creates a new definition if one does not already exist. Section 14.4 discusses the role of the CDD dictionary.
`[GRP2]` | Lists the DECforms form files that are used by the tasks in the task group, the location of those forms on the system, and the label (for reference) that is used within the task definition for each form.
`[GRP3]` | Lists the task definition files that are associated with that task group, and the label that is used for each task. (Typically, the label is the same as the file name, but can be changed for special circumstances.) Note that this particular task group definition names only one task, because this application has only one task, a database inquiry task.
`[GRP4]` | Defines the contents of the procedure server named EMPL_SERVER. The procedure server is a single process that manages the initialization procedure (INIT_EMPL_INFO), the termination procedure (TERM_EMPL_INFO), and all the step procedures (in this case, just a single COBOL procedure named READ_EMPL_INFO).
`[GRP5]` | Lists the different workspaces used by the tasks, forms, and procedures in that group. Workspaces are buffers used for passing data between steps in a task, between a task and a procedure, between a task and a form, and between two or more tasks.

## 14.2.3 Menu Definition

Example 14-7 is an ACMS menu definition (EMPLOYEE_INFO_MENU) that defines the contents of the inquiry menu panel displayed to users. Terminal users can select tasks from this menu. In this example, the menu contains only one task, the inquiry task. In larger applications, multiple options (tasks) are offered on the menu.

Table 14-5 describes the coding in the EMPLOYEE_INFO_MENU menu definition in more detail.

Example 14-7 EMPLOYEE_INFO_MENU Menu Definition

       REPLACE MENU EMPLOYEE_INFO_MENU                                     [MEN1]
       HEADER IS       "              ACMS to IBM Personnel Lookup System";[MEN2]
       ENTRIES ARE                                                         [MEN3]
       "INQUIRY" : TASK IS EMPLOYEE_INFO_READ_TASK IN EMPLOYEE_INFO_APPL_ACMS_APPC;
                   TEXT IS "Inquiry to IBM for an employee record";

       END ENTRIES;
       END DEFINITION;

Table 14-5 Description of Code for EMPLOYEE_INFO_MENU Menu Definition
Callout | Description
--- | ---
`[MEN1]` | Replaces an old CDD dictionary menu definition with the current menu definition or creates a new definition if one does not already exist. Section 14.4 discusses the role of the CDD dictionary.
`[MEN2]` | Defines the text to be displayed at the top of the ACMS menu (the name of the menu).
`[MEN3]` | Defines each menu item (in this case, there is only one menu item: INQUIRY). The menu definition also defines the name of the task definition for each option, the application that the task is in, and the text that is displayed next to each option on the menu.

# 14.3 Additional Procedure Server Components

This section describes the code that:

- Opens all the files and readies databases needed by a group of tasks (INIT_EMPL_INFO initialization procedure)
- Closes at one time all the files and any databases used by a group of tasks (TERM_EMPL_INFO termination procedure)

## 14.3.1 Initialization Procedure

Example 14-8 is the server initialization procedure (INIT_EMPL_INFO) written in COBOL. The server initialization procedure performs work that must be done before the step procedure executes. In this example, the procedure calls an SNA/LU6.2 routine to create the LU6.2 session with the remote IBM computer.

Note Although COBOL is used in this example, users can create procedures using any programming language that supports the OpenVMS Calling Standard.

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

Example 14-8 INIT_EMPL_INFO Initialization Procedure

    IDENTIFICATION DIVISION.
    PROGRAM-ID. INIT_EMPL_INFO.

    ENVIRONMENT DIVISION.
    CONFIGURATION SECTION.
    SOURCE-COMPUTER.  VAX-11.
    OBJECT-COMPUTER.  VAX-11.
    DATA DIVISION.

    WORKING-STORAGE SECTION.                                               [INI1]
    01  status-result           pic S9(9)   comp is external.
    01  status-vec              pic X(64)   is external.
    01  lu-name                 pic X(5)    is external.
    01  nodename-gateway        pic X(6)    is external.
    01  access-name             pic X(7)    is external.
    01  session-status          pic X(1)    is external.
        88 session-connected       value 'Y'.
        88 session-not-connected   value 'N'.
    PROCEDURE DIVISION GIVING STATUS-RESULT.

    MAIN SECTION.
    000-SET-STATUS.

        Set status-result to SUCCESS.

    010-DEFINE-REMOTE.

        Move "ALACK" to nodename-gateway.                                  [INI2]
        Move "XDDXFTB" to access-name.
        Move SPACES to lu-name.
        Set session-not-connected to TRUE.

        Call "SNALU62$DEFINE_REMOTE" using                                 [INI3]
                        by descriptor status-vec,
                        by descriptor lu-name,
                        by descriptor lu-name,
                        by value 0,0,0,0,0,0,
                        by descriptor nodename-gateway,
                        by descriptor access-name,
                        giving status-result.
        IF status-result is SUCCESS                                        [INI4]
                set session-connected to TRUE.

    100-EXIT-PROGRAM.
        EXIT PROGRAM.

Table 14-6 Description of Code for INIT_EMPL_INFO Initialization Procedure
Callout | Description
--- | ---
`[INI1]` | Defines the variables and data types that this procedure uses.
`[INI2]` | Initializes the variables that are used for making the connection with the IBM machine. (For example, the variable nodename-gateway is set to ALACK, the name of the Compaq machine that serves as the network gateway to the IBM network in this sample.)
`[INI3]` | Calls the SNALU62$DEFINE_REMOTE APPC/LU6.2 procedure, which initializes local LU parameters that control the operation of the local LU in conjunction with the remote LU (defines the LU name).
`[INI4]` | Tests the result of the SNALU62$DEFINE_REMOTE APPC/LU6.2 procedure, and, if the operation is successful, sets the session-connected variable to TRUE.

## 14.3.2 Termination Procedure

Example 14-9 is the server termination procedure (TERM_EMPL_INFO) 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 calls an SNA/LU6.2 routine to delete the LU6.2 session with the remote IBM node.

Note Although COBOL is used in this example, users can create procedures using any programming language that supports the OpenVMS Calling Standard.

Table 14-7 describes the coding in the TERM_EMPL_INFO termination procedure in more detail.

Example 14-9 TERM_EMPL_INFO Termination Procedure

       IDENTIFICATION DIVISION.
       PROGRAM-ID. TERM_EMPL_INFO.

       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       SOURCE-COMPUTER.  VAX-11.
       OBJECT-COMPUTER.  VAX-11.
       DATA DIVISION.

       WORKING-STORAGE SECTION.                                            [TRM1]

       01  status-vec              pic X(64)   is external.
       01  lu-name                 pic X(5)    is external.
       01  status-result           pic S9(9)   comp.

       PROCEDURE DIVISION GIVING STATUS-RESULT.

       MAIN SECTION.
       000-SET-STATUS.
           Set status-result to SUCCESS.

       010-DELETE_LU_SESSION.

           call "SNALU62$DELETE" using  by descriptor status-vec,          [TRM2]
                                     by value 0,
                                     by descriptor lu-name,
                              giving status-result.

       100-EXIT-PROGRAM.
           EXIT PROGRAM.

Table 14-7 Description of Code for TERM_EMPL_INFO Termination Procedure
Callout | Description
--- | ---
`[TRM1]` | Defines the variables and data types that this procedure uses.
`[TRM2]` | Calls the SNALU62$DELETE APPC/LU6.2 procedure, which deletes the specified LU name. Any sessions without active conversations are immediately deactivated; sessions with active conversations are deactivated as soon as the conversation is deallocated.

# 14.4 Field and Record Definitions

This section describes some of the field and record definitions that are created and stored in the CDD data dictionary. By using the CDD data dictionary for central storage of field and record definitions, you can modify field and record definitions in one location without needing to make the same modifications to each of the various application components that use those definitions.

CDD is a data dictionary that provides a central storage location for data descriptions and definitions shared by ACMS, other related products (such as DECforms and Rdb), and programming languages. CDD is an active dictionary system that provides the user interface known as Common Dictionary Operator (CDO).

The dictionary contains metadata (descriptions of data, not the data itself) in the form of dictionary definitions. The most commonly used dictionary definitions are fields, records, and databases. CDD objects are stored hierarchically and are accessed by reference to dictionary path names.

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 the sample program, the following employee fields are defined:

- Employee number
- Employee name
- Employee street address
- Employee phone
- Employee date
- Employee amount
- Employee comment

A record definition typically consists of a grouping of field definitions. The sample program defines a record named EMPLOYEE_INFO_RECORD, which contains a group of field definitions corresponding to the preceding fields.

In summary, CDD provides the following:

- Ensures the integrity of shared metadata and the procedures used to analyze, maintain, manage, and design business metadata
- Provides a centralized repository for information management shops
- Offers a dynamic aid to software application development

The CDD field definitions in Example 14-10 specify the information on each field used in the sample application. In addition to the name, each field definition also includes the data type and size (in characters) for each field.

Example 14-10 Field Definitions

       define field empl_number
          datatype text size 6.

       define field empl_name
          datatype text size 20.

       define field empl_street_address
          datatype text size 20.

       define field empl_phone
          datatype text size 8.

       define field empl_date
          datatype text size 8.

       define field empl_amount
          datatype text size 8.

       define field empl_comment
          datatype text size 9.

The sample uses both a record and a workspace (workspaces are buffers used for passing data between steps in a task, between a task and a procedure, between a task and a form, and between two or more tasks). Example 14-11 shows both the record and workspace definitions contained in CDD for this sample.

Example 14-11 Record and Workspace Definitions

       define record employee_info_record.
         empl_number.
         empl_name.
         empl_street_address.
         empl_phone.
         empl_date.
         empl_amount.
         empl_comment.
       end record.

       define record employee_info_wksp.
         empl_number.
         empl_name.
         empl_street_address.
         empl_phone.
         empl_date.
         empl_amount.
         empl_comment.
       end record.

Previous | Next | Contents | Index