| Previous | Contents | Index |
Because of the modularity of the components of ACMS, there are no Oracle-specific issues that relate to the generation of a DECforms form.
DECforms code is typically not hand-generated, but rather is generated
by the DECforms Forms Development Environment, an easy-to-use interface
for forms generation.
12.1.3 Read Database COBOL Step Procedure
The COBOL procedure (VR_GET_SITES_PROC) in Example 12-2, which is a processing step procedure that becomes part of the VR_SERVER procedure server, performs the Oracle database access necessary to return an array of site data back to the task.
Keep the following points in mind when you look at the code example:
Although COBOL is used in this example, users can create server procedures using any programming language that supports the OpenVMS Calling Standard and supports Oracle. This holds true for all COBOL examples in this guide. Writing procedures is fully described in Compaq ACMS for OpenVMS Writing Server Procedures. |
Table 12-2 describes the coding in the VR_GET_SITES_PROC step procedure in more detail.
| Example 12-2 VR_GET_SITES_PROC COBOL Step Procedure |
|---|
IDENTIFICATION DIVISION.
PROGRAM-ID. VR-GET-SITES-PROC.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. VAX-11.
OBJECT-COMPUTER. VAX-11.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 RET-STAT PIC S9(9) COMP. [SRV1]
01 RECNOTFND PIC S9(9) COMP VALUE IS EXTERNAL VR$_SIRECNOTFND. [SRV2]
01 DBFATAL PIC S9(9) COMP VALUE IS EXTERNAL VR$_DB_FATAL.
EXEC SQL [SRV3]
BEGIN DECLARE SECTION
END-EXEC.
01 VR_SI_IND_ARRAY.
05 VR_SI_IND OCCURS 9 TIMES PIC S9(4) COMP.
EXEC SQL
END DECLARE SECTION
END-EXEC.
01 SI-ARRAY-LIMIT PIC S9(9) COMP VALUE IS 60. [SRV4]
01 SQL-SUCCESS PIC S9(9) COMP VALUE IS 0. [SRV5]
01 REC-NOT-FOUND PIC S9(9) COMP VALUE IS +100.
EXEC SQL [SRV6]
INCLUDE AVERTZ_ORACLE_DIR:SQLCA.CBT
END-EXEC.
LINKAGE SECTION. [SRV7]
EXEC SQL
INCLUDE AVERTZ_ORACLE_DIR:VR_SITES_WKSP.LIB
END-EXEC.
EXEC SQL
INCLUDE AVERTZ_ORACLE_DIR:VR_SI_ARRAY_WKSP.LIB
END-EXEC.
PROCEDURE DIVISION USING VR_SITES_WKSP, VR_SI_ARRAY_WKSP GIVING RET-STAT.
MAIN-SECTION. [SRV8]
SET RET-STAT TO SUCCESS.
EXEC SQL
WHENEVER SQLERROR GOTO SQL-ERROR-HANDLER
END-EXEC.
EXEC SQL
DECLARE SITES_ARRAY CURSOR FOR
SELECT * FROM SITES
WHERE SITES.CITY = :WS_CITY
OR
SITES.REGION_ID = :WS_REGION_ID
ORDER BY SITES.SITE_NAME ASC
END-EXEC.
EXEC SQL
WHENEVER NOT FOUND GOTO SQL-NOT-FOUND
END-EXEC.
EXEC SQL
OPEN SITES_ARRAY
END-EXEC.
EXEC SQL
WHENEVER NOT FOUND CONTINUE
END-EXEC.
SET SI_ARRAY_INDEX TO 1.
PERFORM FILL-ARRAY THRU FILL-ARRAY-EXIT UNTIL
(SQLCODE = REC-NOT-FOUND) OR (SI_ARRAY_INDEX > SI-ARRAY-LIMIT).
EXEC SQL
CLOSE SITES_ARRAY
END-EXEC.
EXEC SQL
COMMIT
END-EXEC.
GO TO EXIT-PROGRAM.
FILL-ARRAY.
EXEC SQL
FETCH SITES_ARRAY INTO :WS_SITE_ID,
:WS_SITE_NAME,
:WS_FIRST_ADDRESS_LINE,
:WS_SECOND_ADDRESS_LINE,
:WS_CITY,
:WS_REGION_ID,
:WS_COUNTRY_ID,
:WS_POSTAL_CODE,
:WS_PHONE_NO
END-EXEC.
IF SQLCODE = SQL-SUCCESS
THEN MOVE VR_SITES_WKSP TO SI_ARRAY(SI_ARRAY_INDEX).
SET SI_ARRAY_INDEX UP BY 1.
FILL-ARRAY-EXIT.
EXIT.
SQL-NOT-FOUND.
MOVE RECNOTFND TO RET-STAT.
EXEC SQL
ROLLBACK
END-EXEC.
GO TO EXIT-PROGRAM.
SQL-ERROR-HANDLER.
MOVE SQLCODE TO RET-STAT.
EXEC SQL
WHENEVER SQLERROR CONTINUE
END-EXEC.
GO TO EXIT-PROGRAM.
EXIT-PROGRAM.
EXIT PROGRAM.
|
| Callout | Description |
|---|---|
| [SRV1] | Defines the status that is returned to the task. RET-STAT is returned to the ACMS$L_STATUS field in the ACMS$PROCESSING_STATUS workspace. When the value of ACMS$L_STATUS changes, ACMS internally updates related fields, such as ACMS$T_SEVERITY_LEVEL, which can be tested when control is returned to the task. |
| [SRV2] | Defines an external status that matches up with the message file that is used in the ACMS application. These values can then be used in the task as well. |
| [SRV3] | Declares COBOL variables that are used in the Oracle SQL statements. (These varibles must be included in the DECLARE SECTION.) |
| [SRV4] | Defines the maximum number of sites (60) that can be returned to the task. This number matches the dimensions of the VR_SI_ARRAY_WKSP. |
| [SRV5] | Defines SQL status values. |
| [SRV6] | Includes the Oracle SQL communications area that is updated every time an SQL statement is executed. |
| [SRV7] | Includes the two workspaces that are passed back and forth between the ACMS task and this procedure. The text library includes embedded SQL DECLARE SECTION statements, because the fields in the workspaces are used in the embedded SQL statements in the 3GL code. |
| [SRV8] | Declares a cursor, opens the cursor, fetches data into the cursor and closes the cursor. Control is then returned to the task that called this procedure. This is one of the ways that this code can be distributed between the various portions of procedure server code. (Because this manual assumes Oracle experience, it does not include a detailed explanation of all of the SQL code.) |
Keep the following in mind so that your 3GL server code is interoperable:
When debugging, an application developer's debugging session is different from a multiuser production environment. The application developer is a single user of that instance of the server process and, as such, is automatically guaranteed the same instance throughout the debugging session. The developer must ensure that working storage variables that need to be saved between processing steps in the task are moved into a workspace and passed back and forth between the task and the 3GL code.
After you write an Oracle server procedure, you must compile it. Use the following Oracle SQL precompile statement to compile the VR_GET_SITES_PROC procedure:
$ PROCOBOL HOST=COBOL INAME=vr_get_sites_proc MODE=ANSI FORMAT=TERMINAL - _$ HOLD_CURSOR=Y RELEASE_CURSOR=NO SELECT_ERROR=NO SQLCHECK=SYNTAX |
Execute the following statements to compile the VR_GET_SITES_PROC code with the COBOL compiler, and insert the resulting object into an object library:
$ COBOL vr_get_sites_proc $ LIBRARY ora_obj_lib vr_get_sites_proc |
Once all of the modules are compiled, link them with the following command, where VR_SERVER is the name of the server executable, and VR_OBJECT is the object created for that server when the task group is built with an ACMS ADU BUILD GROUP command:
$ LNPROCOB vr_server vr_object, ora_obj_lib/LIB |
This section describes the code that:
Example 12-3 is an ACMS application definition (AVERTZ_VR_APPLICATION) that defines the characteristics for the application, the servers, and the task groups.
Table 12-3 describes the coding in the AVERTZ_VR_APPLICATION application definition in more detail.
| Example 12-3 AVERTZ_VR_APPLICATION Application Definition |
|---|
REPLACE APPLICATION AVERTZ_VR_APPLICATION [APP1]
AUDIT;
MAX SERVER PROCESS IS 2; [APP2]
MAX TASK INSTANCE IS 5;
APPLICATION USERNAME IS ORAAPP; [APP3]
APPLICATION DEFAULT DIRECTORY IS "AVERTZ_ORACLE_DIR";
TASK DEFAULTS ARE [APP4]
ACCESS CONTROL LIST IS
ID [*,*] ACCESS EXECUTE;
AUDIT;
WAIT;
END TASK DEFAULTS;
SERVER DEFAULTS ARE [APP5]
AUDIT;
DEFAULT DIRECTORY IS "AVERTZ_ORACLE_DIR";
LOGICAL NAME IS ORA_SID = "X1";
MINIMUM SERVER PROCESSES IS 0;
USERNAME IS USERNAME OF APPLICATION;
END SERVER DEFAULTS;
TASK GROUP IS [APP6]
VR_TASK_GROUP: TASK GROUP FILE IS "AVERTZ_ORACLE_DIR:VR_TASK_GROUP";
END TASK GROUP;
END 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 12.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] | Specifies the maximum number of server processes that this application can have running, and the maximum number of task instances that can be active for this application. The maximum number of task instances is larger than the maximum number of server instances because users share server processes serially. |
| [APP3] | Defines the OpenVMS account and default OpenVMS directory for the application. |
| [APP4] | Describes the defaults for each task. The access control list is related to task security. 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. The WAIT clause causes a message to be displayed to the user when a task has finished executing. The user is required to press Return to get back to a menu. The AUDIT and WAIT clauses are optional. |
| [APP5] | Describes the attributes for the procedure server. 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. The DEFAULT DIRECTORY clause associates a default device and directory with the server process. The instance of the AVERTZ Oracle database is known to the server through the use of the logical ORA_SID. The minimum number of server instances for this server is set. The server process runs in the same account as the application. |
| [APP6] | Lists the task group that is associated with this particular application. Although this sample has a single task group, ACMS applications often consist of several tasks groups that contain many tasks in each application. |
Example 12-4 is an ACMS task group definition (VR_TASK_GROUP). The task group definition specifies:
Table 12-4 describes the coding in the VR_TASK_GROUP task group definition in more detail.
| Example 12-4 VR_TASK_GROUP Task Group Definition |
|---|
REPLACE GROUP VR_TASK_GROUP [GRP1]
MESSAGE FILE IS "AVERTZ_ORACLE_DIR:VRMSG.EXE"; [GRP2]
FORMS ARE [GRP3]
VR_RESERVE_CAR_FORM IN "VR_FORMS.EXE" WITH NAME VR_RESERVE_CAR_FORM,
VR_DISPLAY_SITES_FORM IN "VR_FORMS.EXE" WITH NAME VR_DISPLAY_SITES_FORM,
VR_DISPLAY_CU_FORM IN "VR_FORMS.EXE" WITH NAME VR_DISPLAY_CU_FORM;
TASKS ARE [GRP4]
VR_RESERVE_CAR_TASK : TASK IS VR_RESERVE_CAR_TASK;
VR_DISPLAY_SITES_TASK : TASK IS VR_DISPLAY_SITES_TASK;
VR_DISPLAY_CU_TASK : TASK IS VR_DISPLAY_CU_TASK;
END TASKS;
SERVER IS VR_SERVER: [GRP5]
PROCEDURE SERVER IMAGE IS "VR_SERVER.EXE";
PROCEDURES ARE
VR_FIND_SI_PROC,
VR_GET_RATES_PROC,
VR_VERIFY_AVAILABILITY_PROC,
VR_FIND_CU_PROC,
VR_STORE_CU_PROC,
VR_WRITE_RS_PROC,
VR_GET_REGIONS_PROC,
VR_GET_SITES_PROC,
VR_GET_CUSTOMERS_PROC,
VR_MOVE_RE_PROC,
VR_MOVE_SI_PROC,
VR_MOVE_CU_PROC;
INITIALIZATION PROCEDURE IS VR_INIT; [GRP6]
TERMINATION PROCEDURE IS VR_TERM; [GRP7]
DEFAULT OBJECT FILE IS "VR_OBJECT.OBJ";
END SERVER;
END 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 12.4 discusses the role of the CDD dictionary. |
| [GRP2] | Names the message file that is used in the GET ERROR MESSAGE clause in the tasks. |
| [GRP3] | 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. |
| [GRP4] | Lists the task definitions that are associated with that task group and the label that is used for each task. Typically, the label is the same as the name, but can be changed for special circumstances. |
| [GRP5] | Defines the contents of the procedure server named VR_SERVER. The procedure server is a single process that manages the initialization procedure (VR_INIT), the termination procedure (VR_TERM), and all the step procedures. |
| [GRP6] | Names the initialization procedure that is run when the procedure server images starts up. |
| [GRP7] | Names the termination procedure that is run when the procedure server image runs down. |
Example 12-5 is an ACMS menu definition (ACMS_SAMPLE_MENU) that allows users to select a menu or a task. In this example, the menu definition file contains the definitions for a hierarchy of menus. The VR_RESERVE_CAR_TASK in the third-level menu calls the VR_DISPLAY_SITES_TASK described in Section 12.1.1. In larger applications, multiple options (tasks and menus) are typically offered on the menu.
Table 12-5 describes the coding in the ACMS_SAMPLE_MENU menu definition in more detail.
| Example 12-5 ACMS_SAMPLE_MENU Menu Definition |
|---|
REPLACE MENU ACMS_SAMPLE_MENU [MEN1]
HEADER IS " A C M S S a m p l e A p p l i c a t i o n M e n u"; [MEN2]
ENTRIES ARE [MEN3]
AVERTZ_TOP: MENU IS AVERTZ_ORACLE_CDD.AVERTZ_TOP;
TEXT IS "AVERTZ APPLICATION MENU";
END ENTRIES;
END DEFINITION;
REPLACE MENU AVERTZ_TOP
HEADER IS
" A V E R T Z T O P M E N U ";
ENTRIES ARE [MEN4]
VR_MENU: MENU IS AVERTZ_ORACLE_CDD.VR_MENU;
TEXT IS "Vehicle Rental Menu";
END ENTRIES;
END DEFINITION;
REPLACE MENU VR_MENU
HEADER IS
" V E H I C L E R E N T A L M E N U";
ENTRIES ARE [MEN5]
RESERVE: TASK IS VR_RESERVE_CAR_TASK IN O_AVERTZ_VR_APPLICATION;
TEXT IS " Reserve Car Task";
END ENTRIES;
END 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 12.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 first-level menu item. (In this case, there is only one first-level menu item: AVERTZ APPLICATION MENU.) The menu definition also defines the name of the menu definition for the menu item and the text associated with that menu item. Typically, a menu definition consists of multiple entries for tasks and, possibly, additional menus. |
| [MEN4] | Defines each second-level menu item. (In this case, there is only one second-level menu item: Vehicle Rental Menu.) |
| [MEN5] | Defines each third-level menu item. (In this case, there is only one third-level menu item: Reserve Car Task.) |
This section describes the code that:
| Previous | Next | Contents | Index |