Initialization, termination, and cancel procedures make up one type of server procedure. These procedures open files, bind databases, close files, and do cleanup work when an ACMS task is canceled.

Initialization, termination, and cancel procedures do work related to a server process rather than work related to a specific task. The Application Execution Controller (EXC) calls each of them at various times:

Initialization, termination, and cancel procedures for a server are declared in a task group definition. You can have only one initialization, termination, and cancel procedure in each server definition.

      REPLACE GROUP VR_TASK_GROUP 
       . 
       . 
       . 
      SERVER IS VR_SERVER: 
           INITIALIZATION PROCEDURE IS VR_INIT;
           TERMINATION PROCEDURE IS VR_TERM;
           PROCEDURES ARE    
           . 
           . 
           . 
      END SERVER; 
      END DEFINITION;

The declaration of a cancel procedure, if included in the example, would follow the identification of the initialization and termination procedures and would be similar to them.

Chapter 2, "Writing Initialization, Termination, and Cancel Procedures" contains more information and examples of initialization, termination, and cancel procedures.

A step procedure is a second type of server procedure. A step procedure is a subroutine that does the computational and database access work for a processing step in an ACMS task. It is invoked by means of a call statement in a processing step, and it returns control to the calling task when it completes.

Figure 1.2, ''Call to a Step Procedure in a Task Definition'' shows a call to a step procedure in a processing step of a task definition. The step procedure in the example is VR_GET_CUSTOMER_PROC.

             REPLACE GROUP VR_TASK_GROUP
              .
              .
              .
             SERVER IS VR_SERVER:
                  INITIALIZATION PROCEDURE IS VR_INIT;
                  TERMINATION PROCEDURE IS VR_TERM;
                  PROCEDURES ARE    
                                 VR_GET_CUSTOMER_PROC,
                  .
                  .
                  .
             END SERVER;
             END DEFINITION;

In an initialization procedure, you can bind or attach to a database in three ways. The following sections describe these methods and explain how to decide which of them is appropriate to your application.

To bind to a database, start and end a dummy database transaction in the initialization procedure. The examples below illustrate attaching to an Rdb database using SQL; however, the same techniques also apply when accessing an Rdb database using RDO and when accessing a DBMS database.

The following sections contain examples of initialization procedures and explanations of how to write code for Rdb and DBMS databases and for RMS files. See the Rdb, DBMS, and RMS documentation for further information on accessing a database or file.

The initialization procedure for a server that uses an Rdb database attaches to the database by starting and ending a dummy transaction. Note that to attach fully to the database, you must start a transaction, store a dummy record, and roll back the transaction, as explained in Section 2.1.2, ''Binding or Attaching to Databases''.

The initialization procedure for a server using an Rdb database must declare the database accessed by the step procedures in the server. The database declaration in the initialization procedure must be the same as the database declarations in the step procedures in the server. To declare the database using SQL, use the DECLARE SCHEMA statement. Always use the DECLARE SCHEMA statement to name the database you are using before you use other statements that access the database.

In SQL, you start a transaction using the SET TRANSACTION statement. Section 2.1.3.1, ''Specifying the Access Mode and Relations Used by the Server'' describes how to specify the access mode and relations used by the step procedures in the server. If the database transaction cannot be started, log the failure in the ACMS audit trail log by calling SQL$SIGNAL, and then return the failure status to ensure that ACMS stops the server process.

Section 2.1.3.2, ''Using COBOL'' illustrates an initialization procedure written in COBOL that uses SQL. See the SQL documentation for more information about using SQL to access Rdb databases.

         EXEC SQL
                 SET TRANSACTION READ WRITE
                 RESERVING
                     reservations, vehicles, vehicle_rental_history
                         FOR SHARED WRITE,
                     sites, regions
                         FOR SHARED READ
         END-EXEC.

         &RDB& START_TRANSACTION READ_WRITE
         &RDB&   RESERVING
         &RDB&       reservations, vehicles, vehicle_rental_history
         &RDB&           FOR SHARED WRITE,
         &RDB&       sites, regions
         &RDB&           FOR SHARED READ

DATA DIVISION.
WORKING-STORAGE SECTION.
    .
    .
EXEC SQL 
DECLARE EXTERNAL SCHEMA FILENAME AVERTZ_DATABASE:VEHICLE_RENTALS
END-EXEC.

IDENTIFICATION DIVISION.
**************************************************************
PROGRAM-ID. VR-UPDATE-INIT.
*                                                            *
*               Version:        01                           *
*               Edit:           00                           *
*               Authors:        00                           *
*                                                            *
**************************************************************


**************************************************************
*         F U N C T I O N A L   D E S C R I P T I O N        *
*                                                            *
*  This procedure is the initialization procedure for the    *
*  AVERTZ update server. It is used to the open the          *
*  vehicle rental database.                                  *
*                                                            *
**************************************************************
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
**************************************************************
DATA DIVISION.
**************************************************************



WORKING-STORAGE SECTION.
*
* Return status to pass to ACMS
*
01 RET-STAT     PIC S9(9) COMP.
01 ZERO_RESERVATION_ID PIC S9(9) VALUE 0.
*
* Define the SQL return status
*
01 SQLCODE      PIC S9(9) COMP.
01 RDB$MESSAGE_VECTOR EXTERNAL.
    03 Rdb$LU_NUM_ARGUMENTS     PIC S9(9) COMP.
    03 Rdb$LU_STATUS            PIC S9(9) COMP.
    03 Rdb$ALU_ARGUMENTS        OCCURS 18 TIMES.
        05 Rdb$LU_ARGUMENTS     PIC S9(9) COMP.


*
* Declare the database.
*
EXEC SQL
DECLARE EXTERNAL SCHEMA FILENAME AVERTZ_DATABASE:VEHICLE_RENTALS
END-EXEC.



***********************************************************
PROCEDURE DIVISION GIVING RET-STAT.
***********************************************************
MAIN SECTION.

000-OPEN_DB.


*
* Start a recovery unit to force Rdb to bind to the database and read
* in the metadata for the specified relations used by this server.
*
        EXEC SQL
                SET TRANSACTION READ WRITE
                RESERVING
                    RESERVATIONS, VEHICLES, VEHICLE_RENTAL_HISTORY
                        FOR SHARED WRITE,
                    SITES, REGIONS
                        FOR SHARED READ
        END-EXEC.
        IF SQLCODE < ZERO
        THEN
            MOVE RDB$LU_STATUS TO RET-STAT
            CALL "SQL$SIGNAL"
            GO TO 100-EXIT-PROGRAM
        END-IF.



*
* Force Rdb to create the .RUJ file for this server by inserting a
* dummy record into the reservations relation.
*
        EXEC SQL
                INSERT INTO RESERVATIONS
                      (
                       RESERVATION_ID
                      )
               VALUES (
                       :ZERO_RESERVATION_ID
                      )
        END-EXEC.
        IF SQLCODE < ZERO
        THEN
            MOVE RDB$LU_STATUS TO RET-STAT
            CALL "SQL$SIGNAL"
            GO TO 100-EXIT-PROGRAM
        END-IF.



*
* Roll back the recovery unit, deleting the dummy record.
*
        EXEC SQL
                ROLLBACK
        END-EXEC.
        IF SQLCODE < ZERO
        THEN
            MOVE RDB$LU_STATUS TO RET-STAT
            CALL "SQL$SIGNAL"
            GO TO 100-EXIT-PROGRAM
        END-IF.

        SET RET-STAT TO SUCCESS.

100-EXIT-PROGRAM.
        EXIT PROGRAM.

The initialization procedure for a server that uses an Rdb database attaches to the database by starting and ending a dummy transaction. Note that to attach fully to the database, you must start a transaction, store a dummy record, and roll back the transaction, as explained in Section 2.1.2, ''Binding or Attaching to Databases''.

&RDB& INVOKE DATABASE FILENAME "avertz_database:vehicle_rentals"

Start the dummy database transaction by using the START_TRANSACTION statement, which causes Rdb to attach to the database. See Section 2.1.3.1, ''Specifying the Access Mode and Relations Used by the Server'' for information on how to specify the access mode and relations that are used by the server when you start the transaction. If the step procedures in the server write or modify records in the database, use the STORE statement to write a dummy record to the database to force Rdb to create an .RUJ file. Finally, use the ROLLBACK statement to end the dummy transaction and delete the dummy record.

If an error occurs, log the failure in the ACMS audit trail log by signaling the error information in the RDB$MESSAGE_VECTOR array using the LIB$CALLG and LIB$SIGNAL OpenVMS RTL services; then return the failure status to ensure that ACMS stops the server process. For more information on signaling Rdb errors, refer to the Rdb documentation.

     FUNCTION LONG vr_update_init
     !+
     ! Update server initialization procedure.
     !-
 
 
 
     !+
     ! Declare database.
     !-
     &RDB& INVOKE DATABASE FILENAME "avertz_database:vehicle_rentals"
 
 
 
     !+
     ! Declare OpenVMS RTL routines.
     !-
     EXTERNAL LONG FUNCTION  LIB$SIGNAL,                         &
                             LIB$CALLG
 
 
 
     !+
     ! Start a database transaction to force Rdb to attach to 
     ! the database and read in the metadata for the specified 
     ! relations used by this server.
     !-
 
     &RDB& START_TRANSACTION READ_WRITE
     &RDB&   RESERVING
     &RDB&       reservations, vehicles, vehicle_rental_history
     &RDB&           FOR SHARED WRITE,
     &RDB&       sites, regions
     &RDB&           FOR SHARED READ
     &RDB&   ON ERROR
                 CALL LIB$CALLG( Rdb$MESSAGE_VECTOR,             &
                                 LOC( LIB$SIGNAL ) BY VALUE )
                 EXIT FUNCTION Rdb$LU_STATUS
     &RDB&   END_ERROR
 
 
 
     !+
     ! Force Rdb to create the .RUJ file for this server by
     ! inserting a dummy record into the RESERVATIONS relation.
     !-
     &RDB& STORE r IN reservations USING
     &RDB&   ON ERROR
                 CALL LIB$CALLG( Rdb$MESSAGE_VECTOR,             &
                                 LOC( LIB$SIGNAL ) BY VALUE )
                 EXIT FUNCTION Rdb$LU_STATUS
     &RDB&   END_ERROR
     &RDB&   r.RESERVATION_ID = "00000000"
     &RDB& END_STORE
 
 
 
     !+
     ! Roll back the database transaction, deleting the dummy record.
     !-
     &RDB& ROLLBACK
     &RDB&   ON ERROR
                 CALL LIB$CALLG( Rdb$MESSAGE_VECTOR,             &
                                 LOC( LIB$SIGNAL ) BY VALUE )
                 EXIT FUNCTION Rdb$LU_STATUS
     &RDB&   END_ERROR
 
 
 
     !+
     ! Set return status to success and return.
     !-
     vr_update_init = 1%
     END FUNCTION

The initialization procedure for a server that uses a DBMS database binds to the database by starting and ending a dummy transaction. Note that to bind fully to the database, you must start a transaction, store a dummy record, and roll back the transaction, as explained in Section 2.1.2, ''Binding or Attaching to Databases''.

The initialization procedure for a server using a DBMS database must name the database accessed by the step procedures in the server. The database declaration in the initialization procedure must be the same as the database declarations in the step procedures in the server.

DATA DIVISION.

SUB-SCHEMA SECTION.

DB  DEFAULT_SUBSCHEMA
    WITHIN "PERS_CDD.PERSONNEL_SCHEMA"
    FOR "PERS_DB:PERSONNEL".

WORKING-STORAGE SECTION.

01  status_result               PIC S9(5) COMP.

PROCEDURE DIVISION GIVING status_result.

DECLARATIVES.
DML-FAILURE SECTION.
    USE FOR DB-EXCEPTION.
010-DBM-FAILURE.
    MOVE DB-CONDITION TO status_result.
    CALL "DBM$SIGNAL".
    EXIT PROGRAM.
END DECLARATIVES.

MAIN SECTION.

000-start.
    SET status_result TO SUCCESS.

    READY CONCURRENT UPDATE.
    MOVE "000000" TO emp_badge_number.
    STORE employee_record.
    ROLLBACK.

IDENTIFICATION DIVISION.
PROGRAM-ID. pers_upd_server_init_proc.

ENVIRONMENT DIVISION.

DATA DIVISION.
SUB-SCHEMA SECTION.

DB  DEFAULT_SUBSCHEMA
WITHIN "PERS_CDD.PERSONNEL_SCHEMA"
FOR "PERS_DB:PERSONNEL".

WORKING-STORAGE SECTION.

01  status_result               PIC S9(5) COMP.

PROCEDURE DIVISION GIVING status_result.

DECLARATIVES.
DML-FAILURE SECTION.
USE FOR DB-EXCEPTION.
010-DBM-FAILURE.
MOVE DB-CONDITION TO status_result.
CALL "DBM$SIGNAL".
EXIT PROGRAM.
END DECLARATIVES.



MAIN SECTION.

000-start.
SET status_result TO SUCCESS.

READY CONCURRENT UPDATE.
MOVE "000000" TO emp_badge_number.
STORE employee_record.
ROLLBACK.

999-end.
EXIT PROGRAM.

     # INVOKE DEFAULT_SUBSCHEMA -
              WITHIN PERS_CDD.PERSONNEL_SCHEMA -
              FOR PERS_DB:PERSONNEL -
              ( RECORDS )

     # READY CONCURRENT UPDATE
     employee_record::emp_badge_number = "000000"
     # STORE employee_record
     # ROLLBACK

     FUNCTION LONG pers_upd_server_init_proc
 
     %INCLUDE "pers_files:pers_common_defns"
 
     # INVOKE DEFAULT_SUBSCHEMA -
              WITHIN PERS_CDD.PERSONNEL_SCHEMA -
              FOR PERS_DB:PERSONNEL -
              ( RECORDS )
 
 
 
     pers_upd_server_init_proc = persmsg_success
 
     # READY CONCURRENT UPDATE
     employee_record::emp_badge_number = "000000"
     # STORE employee_record
     # ROLLBACK
 
     END FUNCTION
 

An initialization procedure for a server process using RMS opens the files used by the step procedures in the server. The file definitions used in the initialization procedure must be the same as the definitions used in other procedures using those files. If you use a language that assigns channels, the channel number must also be the same in the initialization and step procedures.

If the step procedures in the server require only read access to a file, then open the file for read access only. If the step procedures in the server write to a file, then open the file for read/write access. Specify shared access if more than one server process needs access to the file.

If your step procedures need to lock multiple records in a single record stream or retain record locks after writing or updating a record, you must specify explicit lock control when you open a file.

ENVIRONMENT DIVISION.

INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT  emp_file
ORGANIZATION INDEXED
ACCESS RANDOM
ASSIGN TO "emp_file:employee.dat".



SELECT  hist_file
ORGANIZATION INDEXED
ACCESS RANDOM
ASSIGN TO "hist_file:history.dat".

I-O-CONTROL.
APPLY LOCK-HOLDING ON emp_file,
hist_file.



DATA DIVISION.

FILE SECTION.
FD      emp_file
EXTERNAL
DATA RECORD IS employee_record
RECORD KEY emp_badge_number OF employee_record.
COPY "pers_cdd.employee_record" FROM DICTIONARY.

FD      hist_file
EXTERNAL
DATA RECORD IS history_record
RECORD KEY hist_badge_number OF history_record.
COPY "pers_cdd.history_record" FROM DICTIONARY.

I-O-CONTROL.
APPLY LOCK-HOLDING ON emp_file,
                      hist_file.

WORKING-STORAGE SECTION.
01  file-status                 PIC XX IS EXTERNAL.

WORKING-STORAGE SECTION.

01  status_result               PIC S9(5) COMP.

PROCEDURE DIVISION GIVING status_result.

DECLARATIVES.
employee_file SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON emp_file.
employee_file_handler.
CALL "LIB$SIGNAL" USING BY VALUE RMS-STS OF emp_file,
BY VALUE RMS-STV OF emp_file.
MOVE RMS-STS OF emp_file TO status_result.
EXIT PROGRAM.


history_file SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON hist_file.
history_file_handler.
CALL "LIB$SIGNAL" USING BY VALUE RMS-STS OF hist_file,
BY VALUE RMS-STV OF hist_file.
MOVE RMS-STS OF hist_file TO status_result.
EXIT PROGRAM.
END DECLARATIVES.

MAIN SECTION.

000-start.
SET status_result TO SUCCESS.

OPEN I-O emp_file ALLOWING ALL.
OPEN I-O hist_file ALLOWING ALL.

999-end.
EXIT PROGRAM.

IDENTIFICATION DIVISION.
PROGRAM-ID. pers_upd_server_init_proc.

ENVIRONMENT DIVISION.


INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT  emp_file
ORGANIZATION INDEXED
ACCESS RANDOM
ASSIGN TO "emp_file:employee.dat".


SELECT  hist_file
ORGANIZATION INDEXED
ACCESS RANDOM
ASSIGN TO "hist_file:history.dat".


I-O-CONTROL.
APPLY LOCK-HOLDING ON emp_file,
hist_file.

DATA DIVISION.

FILE SECTION.
FD      emp_file
EXTERNAL
DATA RECORD IS employee_record
RECORD KEY emp_badge_number OF employee_record.
COPY "pers_cdd.employee_record" FROM DICTIONARY.

FD      hist_file
EXTERNAL
DATA RECORD IS history_record
RECORD KEY hist_badge_number OF history_record.
COPY "pers_cdd.history_record" FROM DICTIONARY.


WORKING-STORAGE SECTION.

01  status_result               PIC S9(5) COMP.

PROCEDURE DIVISION GIVING status_result.


DECLARATIVES.
employee_file SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON emp_file.

employee_file_handler.
CALL "LIB$SIGNAL" USING BY VALUE RMS-STS OF emp_file,
BY VALUE RMS-STV OF emp_file.
MOVE RMS-STS OF emp_file TO status_result.
EXIT PROGRAM.

history_file SECTION.
USE AFTER STANDARD ERROR PROCEDURE ON hist_file.

history_file_handler.
CALL "LIB$SIGNAL" USING BY VALUE RMS-STS OF hist_file,
BY VALUE RMS-STV OF hist_file.
MOVE RMS-STS OF hist_file TO status_result.
EXIT PROGRAM.
END DECLARATIVES.


MAIN SECTION.

000-start.
SET status_result TO SUCCESS.

OPEN I-O emp_file ALLOWING ALL.
OPEN I-O hist_file ALLOWING ALL.

999-end.
EXIT PROGRAM.

     %INCLUDE "pers_files:pers_common_defns"
     %INCLUDE %FROM %CDD "pers_cdd.employee_record"
     %INCLUDE %FROM %CDD "pers_cdd.history_record"

     !+
     ! Common definitions for the PERSONNEL application.
     !-
 
     !+
     ! Channel numbers.
     !-
     DECLARE LONG CONSTANT emp_file = 1%
     DECLARE LONG CONSTANT hist_file = 2%
 
 
     !+
     ! Frequently used BASIC error codes.
     !-
     DECLARE LONG CONSTANT basicerr_wait_exhausted = 15%
     DECLARE LONG CONSTANT basicerr_duplicate_key = 134%
     DECLARE LONG CONSTANT basicerr_record_locked = 154%
     DECLARE LONG CONSTANT basicerr_record_not_found = 155%
     DECLARE LONG CONSTANT basicerr_deadlock = 193%
 
 
     !+
     ! Personnel application messages
     !-
     EXTERNAL LONG CONSTANT persmsg_success
     EXTERNAL LONG CONSTANT persmsg_empexists
     EXTERNAL LONG CONSTANT persmsg_empnotfound
     EXTERNAL LONG CONSTANT persmsg_emplocked
     EXTERNAL LONG CONSTANT persmsg_empchanged
     EXTERNAL LONG CONSTANT persmsg_empdeleted
 
 
     !+
     ! Frequently used system services
     !-
     EXTERNAL LONG FUNCTION SYS$GETTIM
 
     !+
     ! ACMS, OpenVMS system and RMS status codes
     !-
     EXTERNAL LONG CONSTANT ACMS$_TRANSTIMEDOUT
     EXTERNAL LONG CONSTANT RMS$_NRU
     EXTERNAL LONG CONSTANT RMS$_DDTM_ERR

     MAP ( emp_map ) employee_record emp_rec
     MAP ( hist_map ) history_record hist_rec

     WHEN ERROR IN
         pers_upd_server_init_proc = persmsg_success
         OPEN  "emp_file:employee.dat"                           &
                     FOR INPUT AS FILE # emp_file,               &
                     ORGANIZATION INDEXED FIXED,                 &
                     ALLOW MODIFY,                               &
                     ACCESS MODIFY,                              &
                     UNLOCK EXPLICIT,                            &
                     MAP emp_map,                                &
                     PRIMARY KEY emp_rec::emp_badge_number
 
         OPEN  "hist_file:history.dat"                           &
                     FOR INPUT AS FILE # hist_file,              &
                     ORGANIZATION INDEXED FIXED,                 &
                     ALLOW MODIFY,                               &
                     ACCESS MODIFY,                              &
                     UNLOCK EXPLICIT,                            &
                     MAP hist_map,                               &
                     PRIMARY KEY hist_rec::hist_badge_number
     USE
         pers_upd_server_init_proc = VMSSTATUS
         EXIT HANDLER
     END WHEN

     FUNCTION LONG pers_upd_server_init_proc
 
     %INCLUDE "pers_files:pers_common_defns"
     %INCLUDE %FROM %CDD "pers_cdd.employee_record"
     %INCLUDE %FROM %CDD "pers_cdd.history_record"
 
     MAP ( emp_map ) employee_record emp_rec
     MAP ( hist_map ) history_record hist_rec
 
     WHEN ERROR IN
         pers_upd_server_init_proc = persmsg_success
         OPEN  "emp_file:employee.dat"                           &
                     FOR INPUT AS FILE # emp_file,               &
                     ORGANIZATION INDEXED FIXED,                 &
                     ALLOW MODIFY,                               &
                     ACCESS MODIFY,                              &
                     UNLOCK EXPLICIT,                            &
                     MAP emp_map,                                &
                     PRIMARY KEY emp_rec::emp_badge_number
 
         OPEN  "hist_file:history.dat"                           &
                     FOR INPUT AS FILE # hist_file,              &
                     ORGANIZATION INDEXED FIXED,                 &
                     ALLOW MODIFY,                               &
                     ACCESS MODIFY,                              &
                     UNLOCK EXPLICIT,                            &
                     MAP hist_map,                               &
                     PRIMARY KEY hist_rec::hist_badge_number
     USE
         pers_upd_server_init_proc = VMSSTATUS
         EXIT HANDLER
     END WHEN
 
     END FUNCTION
 

You do not need to write a termination procedure for a server that uses an Rdb database. When a server process stops, Rdb automatically releases the database used by the process, rolling back a database transaction if one is still active.

In general, if there is a chance that your termination procedure will be called when there is an outstanding database transaction and you are going to use the FINISH verb, include a ROLLBACK verb before the FINISH verb.

Because a transaction is not usually active when the termination procedure runs, the termination procedure should ignore any error from the ROLLBACK verb. Any error returned by the FINISH verb is used as the return status of the termination procedure.

 IDENTIFICATION DIVISION.
 **************************************************************
 PROGRAM-ID. PERS-TERM-PROC.
 **************************************************************
 *         F U N C T I O N A L   D E S C R I P T I O N        *
 *                                                            *
 *   This procedure is used to close the PERSONNEL database.  *
 *                                                            *
 **************************************************************
 ENVIRONMENT DIVISION.
 CONFIGURATION SECTION.
 **************************************************************
 DATA DIVISION.
 **************************************************************
 
 
 WORKING-STORAGE SECTION.
 *
 * return status
 *
 01 RET-STAT     PIC S9(9) COMP.
 *
 * Define the SQL return status
 *
 01 SQLCODE      PIC S9(9) COMP.
 *
 EXEC SQL 
 DECLARE EXTERNAL SCHEMA FILENAME personnel_database:employees
 END-EXEC.
 
 
 **************************************************************
 PROCEDURE DIVISION GIVING RET-STAT.
 **************************************************************
 MAIN SECTION.
 
 000-CLOSE_DB.
 
         SET RET-STAT TO SUCCESS.
 *
 * <<<<Insert application-specific cleanup here>>>>
 *
         EXEC SQL ROLLBACK END-EXEC.
         EXEC SQL FINISH END-EXEC.
         IF SQLCODE < ZERO
         THEN
             MOVE RDB$LU_STATUS TO RET-STAT
             CALL "SQL$SIGNAL"
     END-IF.
 
 100-EXIT-PROGRAM.
         EXIT PROGRAM.
 
 

For more information about SQL, refer to the SQL documentation.

You do not need to write a termination procedure for a server that uses an Rdb database. When a server process stops, Rdb automatically releases the database used by the process, rolling back a database transaction if one is still active.

In general, if there is a chance that your termination procedure will be called when there is an outstanding database transaction, and you are going to use the FINISH verb, include a ROLLBACK verb before the FINISH verb.

     !
     ! <<<<Insert application-specific cleanup here>>>>
     !
     &RDB&   ROLLBACK
     &RDB&   ON ERROR
                 personnel_term_proc = persmsg_success
     &RDB&   END_ERROR
 
     &RDB&   FINISH
     &RDB&   ON ERROR
                 personnel_term_proc = RDB$LU_STATUS
     &RDB&   END_ERROR

You do not need to write a termination procedure for a server that uses a DBMS database. When a server process stops, DBMS automatically unbinds the database used by the process, rolling back a database transaction if one is still active. This section illustrates how to unbind from a DBMS database using the DBMS UNBIND embedded DML statement. Note that there is no UNBIND statement in the COBOL language.

     FUNCTION LONG pers_upd_server_term_proc
 
     %INCLUDE "pers_files:pers_common_defns"
 
     !
     ! <<<<Insert application-specific cleanup here>>>>
     !
     # INVOKE DEFAULT_SUBSCHEMA -
              WITHIN PERS_CDD.PERSONNEL_SCHEMA -
              FOR PERS_DB:PERSONNEL -
              ( RECORDS )
 
     # ROLLBACK ( TRAP ERROR )
     # UNBIND
 
     pers_upd_server_term_proc = persmsg_success
 
     END FUNCTION

If a database transaction is active when a step procedure explicitly unbinds from a database, DBMS returns an error. Therefore, use the ROLLBACK statement to roll back an outstanding transaction. Because there is not usually a transaction active when a termination procedure is executed, ignore any error returned by the ROLLBACK statement. Finally, use the UNBIND statement to unbind from the database.

You do not need to write a termination procedure for a server that uses RMS files. When a server process stops, RMS automatically closes any files that the process has opened. A termination procedure for an RMS server simply closes each open file used by the server, returning a failure status if an error is detected.

 IDENTIFICATION DIVISION.
 PROGRAM-ID. pers_upd_server_term_proc.
 
 
 
 ENVIRONMENT DIVISION.
 
 
 
 INPUT-OUTPUT SECTION.
 FILE-CONTROL.
 SELECT  emp_file
         ORGANIZATION INDEXED
         ACCESS RANDOM
         ASSIGN TO "emp_file:employee.dat".
 
 SELECT  hist_file
         ORGANIZATION INDEXED
         ACCESS RANDOM
         ASSIGN TO "hist_file:history.dat".
 
 
 
 I-O-CONTROL.
 APPLY LOCK-HOLDING ON emp_file,
                       hist_file.
 
 DATA DIVISION.
 
 FILE SECTION.
 FD      emp_file
         EXTERNAL
         DATA RECORD IS employee_record
         RECORD KEY emp_badge_number OF employee_record.
 COPY "pers_cdd.employee_record" FROM DICTIONARY.
 
 
 
 FD      hist_file
         EXTERNAL
         DATA RECORD IS history_record
         RECORD KEY hist_badge_number OF history_record.
 COPY "pers_cdd.history_record" FROM DICTIONARY.
 
 
 
 WORKING-STORAGE SECTION.
 
 01  status_result               PIC S9(5) COMP.
 
 PROCEDURE DIVISION GIVING status_result.
 
 DECLARATIVES.
 employee_file SECTION.
     USE AFTER STANDARD ERROR PROCEDURE ON emp_file.
 
 employee_file_handler.
         CALL "LIB$SIGNAL" USING BY VALUE RMS-STS OF emp_file,
                                 BY VALUE RMS-STV OF emp_file.
         MOVE RMS-STS OF emp_file TO status_result.
 
 history_file SECTION.
     USE AFTER STANDARD ERROR PROCEDURE ON hist_file.
 
 history_file_handler.
         CALL "LIB$SIGNAL" USING BY VALUE RMS-STS OF hist_file,
                                 BY VALUE RMS-STV OF hist_file.
         MOVE RMS-STS OF hist_file TO status_result.
 END DECLARATIVES.
 
 
 
 MAIN SECTION.
 
 000-start.
     SET status_result TO SUCCESS.
 *
 * <<<<Insert application-specific cleanup here>>>>
 *
     CLOSE emp_file.
     CLOSE hist_file.
 
 999-end.
     EXIT PROGRAM.
 

     FUNCTION LONG pers_upd_server_term_proc
 
     %INCLUDE "pers_files:pers_common_defns"
 
 
     !
     ! <<<<Insert application-specific cleanup here>>>>
     !
 
     WHEN ERROR IN
         pers_upd_server_term_proc = persmsg_success
         CLOSE # emp_file
         CLOSE # hist_file
     USE
         pers_upd_server_term_proc = VMSSTATUS
         EXIT HANDLER
     END WHEN
 
     END FUNCTION

There are two important reasons for avoiding cancel procedures. First, cancel procedures can adversely affect application performance. Also, it is often difficult to write a cancel procedure that performs the necessary cleanup operations, chiefly because an exception can be raised at any time while a task is executing. Therefore, it is recommended that wherever possible you avoid designing and writing tasks and step procedures that require server cancel procedures to clean up server processes following an exception.

Section 2.4.3, ''Using $SETAST to Prevent Procedure Server Interruption'', discusses how to prevent the interruption of a procedure server while it is executing. Section 2.3, ''Server Process Rundown'' explains the conditions under which a procedure is run down.

As mentioned earlier, whenever possible avoid designing and writing step procedures that require server cancel procedures. However, in certain circumstances, using a cancel procedure is unavoidable.

     &RDB& START_TRANSACTION
     &RDB&   DISTRIBUTED_TRANSACTION DISTRIBUTED_TID dist_tid
     &RDB&   READ_WRITE RESERVING cust_control FOR SHARED WRITE
 
     &RDB& FOR FIRST 1% c IN cust_control
     &RDB&   GET
     &RDB&       cust_num = c.next_cust_num
     &RDB&   END_GET
             next_cust_num = cust_num + 1%
     &RDB&   MODIFY c USING
     &RDB&       c.next_cust_num = next_cust_num
     &RDB&   END_MODIFY
     &RDB& END_FOR
 

     GET # emp_file,                                             &
         KEY # 0 EQ emp_wksp::emp_badge_number,                  &
         ALLOW NONE
     MOVE TO # emp_file, emp_wksp
     UPDATE # emp_file

See Section 2.4.6, ''Writing a Cancel Procedure'' for information on writing server cancel procedures.

However, setting this window does not guarantee that an event such as a system crash does not interrupt the critical code. Also, this solution does not apply to programs running in DCL servers because the DCL server process handles all cancel requests in supervisor mode.

In this example, if the process is never able to acquire the lock, then the task cancellation sequence can never complete because ACMS can never interrupt the server process. The only way to complete the task cancellation sequence is to delete the server process manually using the DCL STOP command.

 Disable AST delivery
 Call $ENQ service in order to acquire an OpenVMS lock using an
 event flag and using an IOSB.
 If $ENQ returns SS$_NORMAL (we are waiting for the lock to be granted),
 then
 
        Call the $SETIMR service to set a timer.  Pass the same event
        flag that was passed to the $ENQ service.
 
        Call the $WAITFR service to wait for the event flag passed to 
        the two services.  When this service finishes, it means that
        either the $ENQ service has completed or the timer has expired.
        To determine which has occurred, check the IOSB passed to the
        $ENQ service.  If the status in the IOSB is non-zero, the $ENQ
        service completed.
 
 If $ENQ service completed
 then     
        Cancel the timer
 else
        Cancel lock request by calling $DEQ
 
        Enable ASTs
        Call ACMS$RAISE_NONREC_EXCEPTION to cancel the task
 
 If the $ENQ service completed unsuccessfully,
 then
  
        Enable ASTs
   
        Call ACMS$RAISE_NONREC_EXCEPTION to cancel the task
 
 else
 
        Execute the critical code
  
        Release the locking by calling the $DEQ service
 
        Enable ASTs

Stated simply, ACMS calls the cancel procedure defined for each server in which a task is retaining context if either a transaction exception or a nonrecoverable exception is raised while a task is executing. ACMS does not call a server cancel procedure if a step exception is raised while a task is executing and the task handles the exception. If, however, a task does not handle a step exception, and a transaction exception or a nonrecoverable exception is raised as a result, ACMS calls a server cancel procedure, as stated. VSI ACMS for OpenVMS Writing Applications, in its discussion of these conditions as they affect ADU syntax, includes specific examples of task definition syntax.

Section 2.3, ''Server Process Rundown'' discusses the conditions under which ACMS runs down a server process.

             .
             .
             .
   SERVER IS
     pers_upd_server:
        .
        .
       CANCEL PROCEDURE IS pers_upd_server_can_proc;
        .
        .
        .
   END SERVER;
 

ACMS calls the cancel procedure PERS_UPD_SERVER_CAN_PROC under the conditions discussed in Section 2.4.4, ''Conditions Under Which Cancel Procedures Are Called''.

    CANCEL PROCEDURE IS pers_upd_server_can_proc;
    NO RUNDOWN ON CANCEL;

Cancel procedures do not have access to workspaces. Store any information that might be needed by the cancel procedure in global variables while a step procedure is executing. The information is then available to the cancel procedure when it executes.

The following sections illustrate cancel procedures for a server accessing an Rdb database using RDO and for a server accessing an RMS file.

     FUNCTION LONG vr_update_cancel
     !+
     ! Invoke database.
     !-
     &RDB& INVOKE DATABASE FILENAME "avertz_database:vehicle_rentals"
 
     !+
     ! Cancel procedure return status.
     !-
     EXTERNAL LONG CONSTANT ACMS$_RNDWNIFINT
     EXTERNAL LONG CONSTANT ACMS$_RNDWN
 
 
     !+
     ! Rdb error ROLLBACK status code.
     !-
     EXTERNAL LONG CONSTANT RDB$_BAD_TRANS_HANDLE
 
     !+
     ! Error logging routines
     !-
     EXTERNAL LONG FUNCTION LIB$SIGNAL
     EXTERNAL LONG FUNCTION LIB$CALLG
 
 
     !+
     ! Assume success.
     !-
     vr_update_cancel = ACMS$_RNDWNIFINT
 
 
     !+
     ! ROLLBACK an outstanding database transaction. Ignore a
     ! transaction-not-active error. For all other errors, log
     ! the error and return ACMS$_RNDWN to ensure the server
     ! runs down.
     !-
     &RDB& ROLLBACK
     &RDB&   ON ERROR
                 IF Rdb$LU_STATUS <> RDB$_BAD_TRANS_HANDLE
                 THEN
                     CALL LIB$CALLG( Rdb$MESSAGE_VECTOR,             &
                                     LOC( LIB$SIGNAL ) BY VALUE )
                     vr_update_cancel = ACMS$_RNDWN
                 END IF
     &RDB&   END_ERROR
 
     END FUNCTION
 

 IDENTIFICATION DIVISION.
 PROGRAM-ID. pers_upd_server_can_proc.
 
 ENVIRONMENT DIVISION.
 
 
 
 INPUT-OUTPUT SECTION.
 FILE-CONTROL.
 SELECT  emp_file
         ORGANIZATION INDEXED
         ACCESS RANDOM
         ASSIGN TO "emp_file:employee_file.dat".
 
 
 
 SELECT  hist_file
         ORGANIZATION INDEXED
         ACCESS RANDOM
         ASSIGN TO "hist_file:history_file.dat".
 
 I-O-CONTROL.
 APPLY LOCK-HOLDING ON emp_file,
                       hist_file.
 
 
 
 DATA DIVISION.
 
 FILE SECTION.
 FD      emp_file
         EXTERNAL
         DATA RECORD IS employee_record
         RECORD KEY emp_badge_number OF employee_record.
 COPY "pers_cdd.employee_record" FROM DICTIONARY.
 
 
 FD      hist_file
         EXTERNAL
         DATA RECORD IS history_record
         RECORD KEY hist_badge_number OF history_record.
 COPY "pers_cdd.history_record" FROM DICTIONARY.
 
 
 
 WORKING-STORAGE SECTION.
 
 01  status_result               PIC S9(5) COMP.
 
 01  ACMS$_RNDWNIFINT            PIC S9(5) COMP
                                 VALUE IS EXTERNAL ACMS$_RNDWNIFINT.
 01  ACMS$_RNDWN                 PIC S9(5) COMP
                                 VALUE IS EXTERNAL ACMS$_RNDWN.
 
 PROCEDURE DIVISION GIVING status_result.
 
 
 
 DECLARATIVES.
 employee_file SECTION.
     USE AFTER STANDARD ERROR PROCEDURE ON emp_file.
 employee_file_handler.
         CALL "LIB$SIGNAL" USING BY VALUE RMS-STS OF emp_file,
                                 BY VALUE RMS-STV OF emp_file
         MOVE ACMS$_RNDWN TO status_result.
         EXIT PROGRAM.
 history_file SECTION.
     USE AFTER STANDARD ERROR PROCEDURE ON hist_file.
 history_file_handler.
         CALL "LIB$SIGNAL" USING BY VALUE RMS-STS OF hist_file,
                                 BY VALUE RMS-STV OF hist_file
         MOVE ACMS$_RNDWN TO status_result.
         EXIT PROGRAM.
 END DECLARATIVES.
 
 
 
 MAIN SECTION.
 
 000-start.
     UNLOCK emp_file ALL RECORDS.
     UNLOCK hist_file ALL RECORDS.
     MOVE ACMS$_RNDWNIFINT TO status_result.
 
 999-end.
     EXIT PROGRAM.
 

     FUNCTION LONG pers_upd_server_can_proc
 
     %INCLUDE "pers_files:pers_common_defns"
 
     EXTERNAL LONG CONSTANT ACMS$_RNDWNIFINT
     EXTERNAL LONG CONSTANT ACMS$_RNDWN
 
 
 
     WHEN ERROR IN
         FREE # emp_file
         FREE # hist_file
         pers_upd_server_can_proc = ACMS$_RNDWNIFINT
     USE
         pers_upd_server_can_proc = ACMS$_RNDWN
         EXIT HANDLER
     END WHEN
 
     END FUNCTION

ACMS provides special-purpose task workspaces, called system workspaces, which contain information about the state of a task. This information might be useful to the step procedures called by the task.

 REPLACE TASK VR_DISPLAY_CU_TASK
 
 USE WORKSPACES VR_CUSTOMERS_WKSP,
 
 
                       .
                       .
                       .
 BLOCK WORK WITH FORM I/O IS
 
 
 
 GET_CUSTOMERS:
   PROCESSING 
       CALL VR_GET_CUSTOMER_PROC USING VR_CUSTOMERS_WKSP,
                 .
                 .
                 .
 END DEFINITION; 
 

To receive the contents of the workspace named in the task definition, the programming language you use must be able to receive parameters from the calling program. For example, in COBOL, the parameters used to pass information are defined in the Linkage Section and are named in the Procedure Division header.

 IDENTIFICATION DIVISION.
 ***********************************************************
 PROGRAM-ID. VR-GET-CUSTOMER-PROC IS INITIAL.
 . 
 .
 .
 
 
 
 LINKAGE SECTION.
 *
 * Copy CUSTOMERS record from the CDD
 *
 
 
 EXEC SQL INCLUDE FROM DICTIONARY
             'AVERTZ_CDD_WKSP:VR_CUSTOMERS_WKSP'
 END-EXEC.
 .
 .
 .
 
 
 PROCEDURE DIVISION USING VR_CUSTOMERS_WKSP,
                           .
                           .
                           .
                    GIVING RET-STAT.
 

 DEFINE RECORD VR_CUSTOMERS_WKSP.
 .
 .
 .
 CUSTOMER_ID.
 CU_LAST_NAME.
 CU_FIRST_NAME.
 CU_MIDDLE_INITIAL.
 CU_FIRST_ADDRESS_LINE.
 .
 .
 .
 END RECORD.

 DEFINE FIELD CU_LAST NAME                 DATATYPE TEXT SIZE IS 20
         INITIAL VALUE IS "                    ".

See the CDD documentation for additional information on assigning initial values.

See VSI ACMS for OpenVMS Writing Applications for more information on writing definitions of tasks that use distributed transactions.

In ACMS, you can start a distributed transaction in either an agent program, a task, or a step procedure. VSI ACMS for OpenVMS Concepts and Design Guidelines explains the relative advantages and disadvantages of starting a distributed transaction in each of these locations.

You can also start a distributed transaction in a task and, from that task, call a procedure that acts as an agent. The agent program can call a task on a remote node, and the called task can access databases locally on that node, thus reducing network traffic and increasing the efficiency of the application.

The unit of interaction with a database that begins with a start-transaction statement is called a database transaction. The Rdb and DBMS documentation refer to this unit as a transaction. A set of RMS recoverable operations is referred to as a recovery unit. To avoid possible confusion with the term distributed transactions, this manual uses the term database transaction when referring to this unit for Rdb and DBMS database products and recovery unit when referring to this unit for RMS files. The term database transaction is used whether transactions are distributed or nondistributed.

Instructions for starting database transactions are in Chapter 4, "Accessing Resource Managers".

Note that RMS files that are marked for recovery participate automatically in a distributed transaction; in other words, no special syntax is necessary.

The DML verbs COMMIT or ROLLBACK commit or roll back an independent database transaction or a recovery unit that is not participating in a distributed transaction. However, a database transaction that participates in a distributed transaction is automatically committed or rolled back when the distributed transaction ends. Therefore, you cannot use the COMMIT or ROLLBACK DML verbs to end a database transaction that participates in a distributed transaction. The COMMIT and ROLLBACK verbs fail and return an error if you try to use them to end a database transaction that is participating in a distributed transaction.

ACMS automatically obtains a transaction ID (TID) when you start a distributed transaction. Whenever a step procedure is called as part of a distributed transaction, ACMS establishes the TID as the default TID of the server process.

For an Rdb or DBMS database transaction to participate in a distributed transaction, you must explicitly pass the TID to Rdb or DBMS when you start the database transaction. In contrast, RMS automatically accesses the TID for files that are marked for recovery-unit journaling. Therefore, no special action is necessary; a step procedure does not need to obtain the TID when using RMS with distributed transactions.

CALL "ACMS$GET_TID" USING CS-TID GIVING RET_STAT.

See Chapter 9, "ACMS Programming Services" for full details on the ACMS$GET_TID service. See Chapter 4, "Accessing Resource Managers" for information on how to pass the TID to Rdb and DBMS.

If you perform neither of the above steps, the task appears to execute correctly; however, the end of the distributed transaction is not coordinated with the end of the database transaction. This occurs because Rdb or DBMS does not know that you want the database operation to participate in the transaction if you do not pass the TID. Therefore, the database transaction starts and ends as it did before the task was changed to use distributed transactions.

If you perform the first step but not the second, the COMMIT or ROLLBACK statement returns an error. By specifying the TID, you include your database operation in the distributed transaction. You cannot use the COMMIT or ROLLBACK verbs to end a database transaction that is participating in a distributed transaction.

PROCEDURE DIVISION GIVING status-result.

ACMS then sets the values of the fields ACMS$T_SEVERITY_LEVEL and ACMS$T_STATUS_TYPE to correspond to the return status value in ACMS$L_STATUS.

A task can check the ACMS$T_STATUS_TYPE or the ACMS$T_SEVERITY_LEVEL field to determine what action to take.

Returning status to a task in a user-defined workspace is useful if you return a value to DECforms that determines what message DECforms displays.

 CDO> SHOW RECORD pers_cdd.task_control/FULL
 Definition of record TASK_CONTROL
 |   Contains field           STEP_STATUS
 |   |   Datatype                 text size is 8 characters
     .
     .
     . 
 

In Example 3.4, ''Record Description for TASK_CONTROL'', STEP_STATUS is an 8-character text field into which the step procedure writes a character string indicating whether or not it has completed successfully. The task uses the step status field to determine the completion status of the step procedure. The task uses the contents of the workspace field to determine what to do next.

 IDENTIFICATION DIVISION.
 PROGRAM-ID. pers_add_employee_proc.
 
 ENVIRONMENT DIVISION.
 
 INPUT-OUTPUT SECTION.
 FILE-CONTROL.
 SELECT  emp_file
         ORGANIZATION INDEXED
         ACCESS RANDOM
         ASSIGN TO "emp_file:employee.dat".
 
 I-O-CONTROL.
 APPLY LOCK-HOLDING ON emp_file.
 
 DATA DIVISION.
 
 FILE SECTION.
 FD      emp_file
         EXTERNAL
         DATA RECORD IS employee_record
         RECORD KEY emp_badge_number OF employee_record.
 COPY "pers_cdd.employee_record" FROM DICTIONARY.
 WORKING-STORAGE SECTION.
 
 LINKAGE SECTION.
 COPY "pers_cdd.task_control" FROM DICTIONARY.
 COPY "pers_cdd.employee_record" FROM DICTIONARY
     REPLACING ==employee_record== BY ==emp_wksp_record==.
 
 PROCEDURE DIVISION USING task_control, emp_wksp_record.
 MAIN SECTION.
 
 000-start.
     MOVE "SUCCESS" TO step_status OF task_control.
     WRITE employee_record FROM emp_wksp_record
         ALLOWING NO OTHERS
         INVALID KEY
             MOVE "DUPLICAT" TO step_status OF task_control
         NOT INVALID KEY
             UNLOCK emp_file ALL RECORDS
     END-WRITE.
 
 999-end.
     EXIT PROGRAM.

     FUNCTION LONG pers_add_employee_proc(                       &
                                 task_control task_ctrl_wksp,    &
                                 employee_record emp_wksp )
 
     %INCLUDE "pers_files:pers_common_defns"
 
     %INCLUDE %FROM %CDD "pers_cdd.employee_record"
     %INCLUDE %FROM %CDD "pers_cdd.task_control"
 
     MAP ( emp_map ) employee_record emp_rec
 
     WHEN ERROR IN
         task_ctrl_wksp::step_status = "SUCCESS"
         MOVE TO # emp_file, emp_wksp
         PUT # emp_file
         UNLOCK # emp_file
     USE
         SELECT ERR
             CASE basicerr_duplicate_key
                 task_ctrl_wksp::step_status = "DUPLICAT"
             CASE ELSE
                 CALL ACMS$RAISE_NONREC_EXCEPTION( RMSSTATUS( emp_file ) )
                 EXIT HANDLER
         END SELECT
     END WHEN
 
     END FUNCTION

If a step procedure detects a recoverable error, you must inform users of the problem. With this information, they can then decide how to continue.

     "Employee ID already exists on file"

 "Employee ID: 123456, last name: SMITH, already exists on file"

The ACMS exception services differ in an important way from the superseded ACMSAD$REQ_CANCEL service. Whereas the ACMSAD$REQ_CANCEL service immediately cancels the current task and does not return control to the step procedure, the ACMS exception services all return control to the step procedure after setting the appropriate exception condition. This allows the step procedure to clean up any context in the server and to complete normally.

Allowing the step procedure to complete before raising the exception in the task means that ACMS does not have to interrupt the server process. Therefore, if a step procedure uses one of the exception services to raise an exception, and you have specified that your server is to be run down on cancel only if it is interrupted, ACMS does not need to run down the server process. See Section 2.3, ''Server Process Rundown'' for details on how to specify when ACMS should run down your server.

Example 4.2, ''Declaring the Database'' contains examples illustrating each of these guidelines.

For other high-level languages, the rules for beginning and ending SQL statements in step procedures vary. See the SQL documentation for more information about beginning and ending SQL statements in step procedures.

Before you can use SQL to access a database, you must declare the database. You do this in each server procedure that accesses the database. If you are using COBOL, name the Rdb database in the Working-Storage Section of the Data Division of your procedure using the DECLARE SCHEMA statement. This must appear in the procedure before you can use other SQL statements to reference data in the database.

 ************************************************************
 DATA DIVISION.
 ************************************************************
 WORKING-STORAGE SECTION.
 * 
 *  Return status to pass to ACMS
 *
 01 RET-STAT      PIC S9(9) COMP.
 01 RSTAT         PIC S9(9) COMP.
 
 
 .
 .
 .
 *
 *  Declare the database schema.
 *
 EXEC SQL
    DECLARE EXTERNAL SCHEMA FILENAME AVERTZ_DATABASE:VEHICLE_RENTALS
 END-EXEC.

When you use SQL with a distributed transaction, you must pass the transaction ID (TID) to SQL on each executable DML verb using an SQL context structure.

See Example 4.7, ''COBOL Procedure Using SQL with Rdb'' for a complete example of using precompiled SQL in a distributed transaction using COBOL. See the SQL documentation for information on how to define and use an SQL context structure.

     WORKING-STORAGE SECTION.
                .
                .
                .
     01 context-structure.
             02 cs-version           PIC S9(9) COMP VALUE 1.
             02 cs-type              PIC S9(9) COMP VALUE 1.
             02 cs-length            PIC S9(9) COMP VALUE 16.
             02 cs-tid               PIC X(16).
             02 cs-end               PIC S9(9) COMP VALUE 0.
                .
                .
                .

     WORKING-STORAGE SECTION.
                .
                .
                .
     EXEC SQL
         INCLUDE 'AVERTZ_SOURCE:VR_CONTEXT_STRUCTURE_INCLUDE.LIB'
     END-EXEC.
                .
                .
                .

     RECORD sql_context_structure
         LONG sqlctx_version
         LONG sqlctx_type
         LONG sqlctx_length
         STRING sqlctx_tid = 16
         LONG sqlctx_end
     END RECORD sqlctx_structure
 
 
 
     DECLARE sql_context_structure sqlcs
 
     sqlcs::sqlctx_version = 1%
     sqlcs::sqlctx_type = 1%
     sqlcs::sqlctx_length = 16%
     sqlcs::sqlctx_end = 0%

     %INCLUDE "pers_files:pers_sqlctx"

     CALL "ACMS$GET_TID" USING BY REFERENCE cs-tid
                         GIVING ret-stat.
     IF ret-stat IS NOT SUCCESS
     THEN
         CALL "ACMS$RAISE_NONREC_EXCEPTION" 
                         USING BY REFERENCE ret-stat
         GO TO 999-end
     END-IF.
 

     sts = ACMS$GET_TID( sqlcs::sqlctx_tid BY REF )
     IF ( sts AND 1% ) = 0% THEN
         CALL ACMS$RAISE_NONREC_EXCEPTION( sts )
         EXIT FUNCTION
     END IF
 

You start an SQL database transaction by using a SET TRANSACTION statement. However, the way in which you start the database transaction depends on whether the database transaction is part of a distributed transaction.

This section describes how to start a database transaction that is part of a distributed transaction and how to start and end an independent database transaction. In addition, this section discusses various access modes that you can specify when starting a database transaction.

     EXEC SQL USING CONTEXT :context-structure
         SET TRANSACTION READ WRITE
         RESERVING reservations FOR SHARED WRITE,
                   rental_classes,sites,regions FOR SHARED READ
     END-EXEC.

     EXEC SQL USING CONTEXT
         SET TRANSACTION READ WRITE
         RESERVING reservations FOR SHARED WRITE,
                   rental_classes,sites,regions FOR SHARED READ
     END-EXEC.
 

     IF step-proc-status IS SUCCESS
     THEN
         EXEC SQL
             COMMIT
         END-EXEC
     ELSE
         EXEC SQL
             ROLLBACK
         END-EXEC
     END-IF.

      EXEC SQL USING CONTEXT :CONTEXT-STRUCTURE
              SET TRANSACTION READ WRITE 
               .
               .
               .
              RESERVING  RESERVATIONS,
                         VEHICLES,
                         VEHICLE_RENTAL_HISTORY
              FOR        SHARED WRITE,
                         RENTAL_CLASSES,
                         SITES,
                         REGIONS 
              FOR        SHARED READ
      END-EXEC.
 

    LOGICAL NAME IS
         RDM$BIND_LOCK_TIMEOUT_INTERVAL = "10";

The procedure VR_COMPLETE_CHECKOUT_PROC from the AVERTZ Sample Application illustrates the use of SQL statements in reading information from an Rdb database. As part of the processing associated with checking out a car, the procedure must find the current odometer reading for the selected vehicle. It does this by selecting the record with the highest odometer reading from the VEHICLE_RENTAL_HISTORY relation. Because the vehicle history record might contain a null value, the procedure uses an indicator parameter to determine whether or not an odometer reading has been retrieved.

Example 4.4, ''Indicator Array for Null Values'' illustrates how the procedure VR_COMPLETE_CHECKOUT_PROC declares an indicator array (for a subsequent STORE operation) and an indicator parameter (for the SELECT operation). You need to include this when a read operation on the database might return a null value. Example 4.4, ''Indicator Array for Null Values'' shows one way this can appear in a COBOL program.

 *
 * Indicator array for null values
 *
 01 VR_VRH_IND_ARRAY.
    05 VR_VRH_IND OCCURS 6 TIMES  PIC S9(4) COMP.
 01 VR_VRH_IND1                   PIC S9(4) COMP.

 GET-ODOMETER-READING.
 * Get the last return odometer reading for the vehicle being 
 * checked out from the database.  If not found, ignore it.
         .
         .
         .
         EXEC SQL USING CONTEXT :CONTEXT-STRUCTURE
            SELECT MAX(RETURN_ODOMETER_READING)INTO
                  :VR_VEHICLE_RENTAL_HISTORY_WKSP.CHECKOUT_ODOMETER_READING
                     INDICATOR :VR_VRH_IND1
               FROM VEHICLE_RENTAL_HISTORY
               WHERE VEHICLE_ID = :VR_VEHICLES_WKSP.VEHICLE_ID
         END-EXEC.
 

You typically write an error handler to process errors returned by Rdb when starting and ending a database transaction and when accessing data in the database. When you use Rdb with SQL, you have normal direct access to the same status values as you do when you use Rdb with RDO. The Rdb return status values are inherently compatible with OpenVMS usage.

Some Rdb errors are expected and are handled by resuming normal program execution. For example, Rdb returns an end-of-stream error when the last record in a record stream has been processed. In this case, the program can resume execution and process the records that have been read. Rdb can also return a number of recoverable errors that the program should check for and handle. For example, if Rdb returns a deadlock error, you might want to roll back the transaction and process the transaction again. Finally, Rdb can return a number of nonrecoverable errors. For example, a disk on which one of the database storage areas resides might fail. In this case, the program cannot continue until the problem has been resolved.

A distributed transaction can abort at any time. If a transaction aborts while a step procedure is executing, Rdb automatically rolls back an active database transaction. However, the step procedure will receive an error the next time it executes an SQL statement in a database transaction that was participating in the distributed transaction. Therefore, an error handler for a step procedure should check for and handle the errors that Rdb returns in this situation.

Typically, you want to retry a transaction automatically in the event of a recoverable error condition such as a deadlock, lock-conflict, lock-timeout, or transaction-timeout error. Rdb returns deadlock, lock-conflict, and lock-timeout errors to your step procedure when you access the database. In contrast, if a distributed transaction times out, the distributed transaction is aborted and ACMS raises a transaction exception in the task. In this case, Rdb returns an error if the step procedure accesses the database after the transaction has aborted.

For detailed information on SQL error handling, see the SQL documentation.

You use the SQL precompiler, SQLPRE, when you compile a procedure containing embedded SQL statements. The SQL precompiler processes the embedded SQL statements in your program, producing an intermediate host-language source file, which it then submits to the host-language compiler to produce an object module.

The SQL precompiler command line includes both precompiler and host-language compiler qualifiers. For the precompiler, include a qualifier to specify in which host language the source is written; you can, optionally, include other qualifiers. On the command line, also include any language compiler qualifiers (such as LIST or DEBUG) that you want in effect when the precompiler submits the preprocessed source file to the language compiler. For more information on SQL precompiler qualifiers, see the SQL documentation.

$ SCOB == "$SQLPRE/COBOL"

$ SCOB/LIST VR_COMPLETE_CHECKOUT_PROC

Chapter 6, "Building Procedure Server Images" explains how to link procedures that use SQL.

Example 4.7, ''COBOL Procedure Using SQL with Rdb'' contains a complete COBOL procedure that accesses an Rdb database using SQL.

 IDENTIFICATION DIVISION.
 **************************************************************
 PROGRAM-ID. VR-COMPLETE-CHECKOUT-PROC.
 *                                                            *
 *               Version:        01                           *
 *               Edit:           00                           *
 *               Authors:        00                           *
 *               Called from:    VR_COMPLETE_CHECKOUT_TASK    *
 *                                                            *
 **************************************************************
 
 **************************************************************
 *         F U N C T I O N A L   D E S C R I P T I O N        *
 *                                                            *
 *   This procedure is called from the VR_COMPLETE_CHECKOUT_  *
 *   TASK and is used to write a completed reservation record *
 *   an updated vehicle record and a new vehicle_rental_his-  *
 *   tory record to the VEHICLE_RENTALS database.             *
 **************************************************************
 ENVIRONMENT DIVISION.
 **************************************************************
 DATA DIVISION.
 **************************************************************
 
 
 WORKING-STORAGE SECTION.
 *
 * Return status to pass to ACMS
 *
 01 RET-STAT     PIC S9(9) COMP.
 01 RSTAT        PIC S9(9) COMP.
 
 
 *
 * External variables
 *
 01 RDMS$_DEADLOCK        PIC S9(9) COMP VALUE IS EXTERNAL RDMS$_DEADLOCK.
 01 RDB$_DEADLOCK         PIC S9(9) COMP VALUE IS EXTERNAL RDB$_DEADLOCK.
 01 RDMS$_LCKCNFLCT       PIC S9(9) COMP VALUE IS EXTERNAL RDMS$_LCKCNFLCT.
 01 RDB$_LOCK_CONFLICT    PIC S9(9) COMP VALUE IS EXTERNAL RDB$_LOCK_CONFLICT.
 01 RDMS$_TIMEOUT         PIC S9(9) COMP VALUE IS EXTERNAL RDMS$_TIMEOUT.
 01 ACMS$_TRANSTIMEDOUT   PIC S9(9) COMP VALUE IS EXTERNAL ACMS$_TRANSTIMEDOUT.
 01 RDB$_SYS_REQUEST_CALL PIC S9(9) COMP VALUE IS EXTERNAL RDB$_SYS_REQUEST_CALL.
 01 RDB$_BAD_TRANS_HANDLE PIC S9(9) COMP VALUE IS EXTERNAL RDB$_BAD_TRANS_HANDLE.
 01 RDB$_DISTABORT        PIC S9(9) COMP VALUE IS EXTERNAL RDB$_DISTABORT.
 01 LIB$SIGNAL            PIC S9(5) COMP VALUE IS EXTERNAL LIB$SIGNAL.
 
 
 
 *
 * Indicator array for null values
 *
 01 VR_VRH_IND_ARRAY.
    05 VR_VRH_IND OCCURS 6 TIMES PIC S9(4) COMP.
 01 VR_VRH_IND1                  PIC S9(4) COMP.
 * External status variables for VR messages.
 *
 EXEC SQL INCLUDE
         'AVERTZ_SOURCE:VR_MESSAGES_INCLUDE.LIB'
 END-EXEC.
 
 
 *
 * Literals
 *
 EXEC SQL INCLUDE
         'AVERTZ_SOURCE:VR_LITERALS_INCLUDE.LIB'
 END-EXEC.
 *
 * Define the SQL return status
 *
 EXEC SQL INCLUDE
         'AVERTZ_SOURCE:VR_SQL_STATUS_INCLUDE.LIB'
 END-EXEC.
 
 
 *
 * Declare the global transaction context structure. This is required for SQLPRE
 *
 EXEC SQL INCLUDE
         'AVERTZ_SOURCE:VR_CONTEXT_STRUCTURE_INCLUDE.LIB'
 END-EXEC.
 *
 * Get structure for SQLCODE and RDB$MESSAGE_VECTOR.
 *
 EXEC SQL INCLUDE SQLCA END-EXEC.
 
 
 *
 * Declare the database schema
 *
 *
 * Copy VEHICLE_RENTAL_HISTORY from the CDD
 *
 EXEC SQL INCLUDE FROM DICTIONARY
             'AVERTZ_CDD_WKSP:VR_VEHICLE_RENTAL_HISTORY_WKSP'
 END-EXEC.
 
 
 *
 EXEC SQL
    DECLARE EXTERNAL SCHEMA FILENAME AVERTZ_DATABASE:VEHICLE_RENTALS
 END-EXEC.
 
 **************************************************************
 LINKAGE SECTION.
 
 
 *
 * Copy RESERVATIONS from the CDD
 *
 EXEC SQL INCLUDE FROM DICTIONARY
             'AVERTZ_CDD_WKSP:VR_RESERVATIONS_WKSP'
 END-EXEC.
 *
 * Copy VEHICLES from the CDD
 *
 EXEC SQL INCLUDE FROM DICTIONARY
             'AVERTZ_CDD_WKSP:VR_VEHICLES_WKSP'
 END-EXEC.
 * Copy CONTROL workspace from the CDD - used to handle DDTM timeout
 *
 EXEC SQL INCLUDE FROM DICTIONARY
             'AVERTZ_CDD_WKSP:VR_CONTROL_WKSP'
 END-EXEC.
 
 
 **************************************************************
 PROCEDURE DIVISION USING VR_RESERVATIONS_WKSP,
                          VR_VEHICLES_WKSP,
                          VR_CONTROL_WKSP
                    GIVING RET-STAT.
 **************************************************************
 
 
 MAIN-PROGRAM.
 
         SET RET-STAT TO SUCCESS.
 
         IF INCREMENT_RETRY_COUNT OF VR_CONTROL_WKSP = "Y"
         THEN
                 ADD 1 TO RETRY_COUNT OF VR_CONTROL_WKSP
         END-IF.
 
         CALL "ACMS$GET_TID" USING CS-TID GIVING RET-STAT.
         IF RET-STAT IS NOT SUCCESS THEN
                 CALL "ACMS$RAISE_NONREC_EXCEPTION" USING BY REFERENCE RET-STAT
                 GO TO EXIT-PROGRAM
         END-IF.
 
 
 
 *
 * Update the required record fields and DECLARE The appropriate null indicators
 *
         MOVE VEHICLE_CHECKOUT_SITE_ID OF VR_RESERVATIONS_WKSP TO
            CHECKOUT_SITE_ID OF VR_VEHICLE_RENTAL_HISTORY_WKSP.
         MOVE VEHICLE_ID OF VR_VEHICLES_WKSP TO
            VEHICLE_ID OF VR_VEHICLE_RENTAL_HISTORY_WKSP.
         MOVE RESERVATION_ID OF VR_RESERVATIONS_WKSP TO
            RESERVATION_ID OF VR_VEHICLE_RENTAL_HISTORY_WKSP.
         MOVE NEG-ONE TO VR_VRH_IND(5).
         MOVE NEG-ONE TO VR_VRH_IND(6).
 
 
 
 * Set up to trap errors returned by SQL;  the precompiler will generate the
 * necessary tests
 *
         EXEC SQL
            WHENEVER SQLERROR GO TO SQL-ERROR-HANDLER
         END-EXEC.
 
 
 
 
 * Start the database transaction
 *
         EXEC SQL USING CONTEXT: CONTEXT_STRUCTURE
                 SET TRANSACTION READ WRITE
                 EVALUATING RS_VALID_BILL_RENTAL_CLASS AT VERB TIME,
                 RS_VALID_VEHICL_CHKOUT_SITE_ID AT VERB TIME,
                 VE_VALID_CURRENT_SITE_ID AT VERB TIME,
                 VRH_VALID_VEHICLE_ID AT VERB TIME,
                 VRH_VALID_PRIMARY_KEY AT VERB TIME
                 RESERVING RESERVATIONS,VEHICLES,VEHICLE_RENTAL_HISTORY
                    FOR SHARED WRITE,
                 RENTAL_CLASSES,SITES,REGIONS FOR SHARED READ
         END-EXEC.
 
 
 *
 *
 GET-ODOMETER-READING.
 * Get the last return odometer reading for the vehicle being checked out
 * from the database.  If not found, ignore it.
         EXEC SQL WHENEVER NOT FOUND CONTINUE END-EXEC.
 
         EXEC SQL USING CONTEXT :CONTEXT-STRUCTURE
            SELECT MAX(RETURN_ODOMETER_READING)INTO
                  :VR_VEHICLE_RENTAL_HISTORY_WKSP.CHECKOUT_ODOMETER_READING
                     INDICATOR :VR_VRH_IND1
               FROM VEHICLE_RENTAL_HISTORY
               WHERE VEHICLE_ID = :VR_VEHICLES_WKSP.VEHICLE_ID
         END-EXEC.
 
 
 
 UPDATE-RESERVATION.
 * Update the reservation in the database
 *
         EXEC SQL USING CONTEXT :CONTEXT-STRUCTURE
            UPDATE RESERVATIONS
               SET CREDIT_CARD_NO = :VR_RESERVATIONS_WKSP.CREDIT_CARD_NO,
                   CREDIT_CARD_TYPE_ID =
                      :VR_RESERVATIONS_WKSP.CREDIT_CARD_TYPE_ID,
                   RESERV_STATUS_FLAG = :C-ONE,
                   RESERV_MODIFIC_FLAG =
                      :VR_RESERVATIONS_WKSP.RESERV_MODIFIC_FLAG,
                   BILL_RENTAL_CLASS_ID =
                      :VR_RESERVATIONS_WKSP.BILL_RENTAL_CLASS_ID,
                   VEHICLE_EXPECTED_RETURN_DATE =
                      :VR_RESERVATIONS_WKSP.VEHICLE_EXPECTED_RETURN_DATE
               WHERE RESERVATION_ID = :VR_RESERVATIONS_WKSP.RESERVATION_ID
         END-EXEC.
 
 
 
 * Update the vehicle record in the database
 *
 UPDATE-VEHICLES.
 *
         EXEC SQL USING CONTEXT :CONTEXT-STRUCTURE
            UPDATE VEHICLES
               SET CURRENT_SITE_ID =
                      :VR_RESERVATIONS_WKSP.VEHICLE_CHECKOUT_SITE_ID,
                   AVAILABLE_FLAG = :C-ZERO
               WHERE VEHICLE_ID = :VR_VEHICLES_WKSP.VEHICLE_ID
         END-EXEC.
 
 
 
 * Write a new vehicle_rental_history record to the database
 *
         EXEC SQL USING CONTEXT :CONTEXT-STRUCTURE
            INSERT INTO VEHICLE_RENTAL_HISTORY
               VALUES (:VR_VEHICLE_RENTAL_HISTORY_WKSP:VR_VRH_IND)
         END-EXEC.
 
 * All database activity was successful; commit the transaction in the task
 *
 
         MOVE CHKOUTCOM TO RET-STAT.
 
         GO TO EXIT-PROGRAM.
 
 * Error handling
 
 
 
 SQL-ERROR-HANDLER.
 
     EVALUATE TRUE
         WHEN ( ( Rdb$LU_STATUS = RDB$_DEADLOCK ) OR
                ( Rdb$LU_STATUS = RDMS$_DEADLOCK ) OR
                ( Rdb$LU_STATUS = RDB$_LOCK_CONFLICT ) OR
                ( Rdb$LU_STATUS = RDMS$_LCKCNFLCT ) OR
                ( Rdb$LU_STATUS = RDMS$_TIMEOUT ) )
             CALL "ACMS$RAISE_TRANS_EXCEPTION" USING
                         BY REFERENCE ACMS$_TRANSTIMEDOUT
 
 
 
         WHEN ( ( RdB$LU_STATUS = RDB$_SYS_REQUEST_CALL ) OR
                ( Rdb$LU_STATUS = RDB$_BAD_TRANS_HANDLE ) OR
                ( Rdb$LU_STATUS = RDB$_DISTABORT ) OR
                ( Rdb$LU_STATUS = RDB$_REQ_SYNC ) OR
                ( Rdb$LU_STATUS = RDB$_READ_ONLY_TRANS ) ) 
             CALL "ACMS$RAISE_TRANS_EXCEPTION" USING
                         BY REFERENCE Rdb$LU_STATUS
 
 
 
         WHEN OTHER
             CALL "LIB$CALLG" USING 
                         BY REFERENCE Rdb$MESSAGE_VECTOR,
                         BY VALUE LIB$SIGNAL
             CALL "ACMS$RAISE_NONREC_EXCEPTION" USING
                         BY REFERENCE Rdb$LU_STATUS
     END-EVALUATE.
 
 
 
 EXIT-PROGRAM.
         EXIT PROGRAM.

   &RDB&  INVOKE DATABASE FILENAME "avertz_database:vehicle_rentals"

The database you name must be the same in all the step procedures, and in the initialization and termination procedures and cancel procedures in the server.

You start an RDO database transaction by using a START_TRANSACTION statement. However, the way in which you start the database transaction depends on whether the database transaction is part of a distributed transaction.

            .
            .
            .
 WORKING-STORAGE SECTION.
 
 
 
 &RDB& INVOKE DATABASE FILENAME "avertz_database:vehicle_rentals"
 
 01 dist_tid.
    03 tid_data                  PIC X(16).
 01 sts                          PIC S9(5) COMP.
       .    
       .
       .
 
 
 PROCEDURE DIVISION.
 MAIN SECTION.
       .
       .
       .
     CALL "ACMS$GET_TID" USING BY REFERENCE dist_tid
                         GIVING sts.
     IF sts IS FAILURE
     THEN
         CALL "ACMS$RAISE_NONREC_EXCEPTION" USING BY REFERENCE sts
         GO TO 999_end
     END-IF.
 
 
 
     &RDB& START_TRANSACTION DISTRIBUTED_TRANSACTION 
     &RDB&   DISTRIBUTED_TID dist_tid READ_WRITE 
     &RDB&   RESERVING reservations FOR SHARED WRITE,
     &RDB&            rental_classes,sites,regions FOR SHARED READ
     &RDB&   ON ERROR
                 GO TO 900-rdb-error
     &RDB&   END_ERROR.
           .
           .
           .
 

     .
     .                         
     .                         
     &RDB& INVOKE DATABASE FILENAME "avertz_database:vehicle_rentals"
 
     RECORD dist_tid_structure
         STRING tid_data = 16
     END RECORD
 
 
 
     DECLARE dist_tid_structure dist_tid
 
     sts = ACMS$GET_TID( dist_tid )
     IF ( sts AND 1% ) = 0%
     THEN
         CALL ACMS$RAISE_NONREC_EXCEPTION( sts )
         EXIT FUNCTION sts
     END IF
 
 
 
     &RDB& START_TRANSACTION DISTRIBUTED_TRANSACTION 
     &RDB&   DISTRIBUTED_TID dist_tid READ_WRITE 
     &RDB&   RESERVING reservations FOR SHARED WRITE,
     &RDB&             rental_classes,sites,regions FOR SHARED READ
     &RDB&   ON ERROR
                 GOSUB check_rdb_error
                 EXIT FUNCTION Rdb$LU_STATUS
     &RDB&   END_ERROR
           .
           .
           .
 

     &RDB& START_TRANSACTION 
     &RDB&   RESERVING reservations FOR SHARED WRITE,
     &RDB&             rental_classes,sites,regions FOR SHARED READ
     &RDB&   ON ERROR
                 .
                 .
                 .
     &RDB&   END_ERROR
 

     IF sts IS SUCCESS
     THEN
         &RDB& COMMIT
     ELSE
         &RDB& ROLLBACK
     END-IF.
 

The examples in this section illustrate how to read a record from a database and retrieve the data from the record.

             .
             .
             .
     MOVE vr_sirecnotfnd TO return_status.
     &RDB& FOR s IN sites WITH s.site_id = site_id
     &RDB&   ON ERROR
                 GO TO 900-rdb-error
     &RDB&   END_ERROR
     &RDB&   GET
     &RDB&       ON ERROR
                     GO TO 900-rdb-error
     &RDB&       END_ERROR
     &RDB&       vr_sites_wksp = s.*
     &RDB&   END_GET
             SET return_status TO SUCCESS
     &RDB& END_FOR.
             .
             .
             .
 

             .
             .
             .
     vr_find_site_proc = vr_sirecnotfnd
     &RDB& FOR s IN sites WITH s.site_id = sites::site_id
 
 
     &RDB&   ON ERROR
                 GOSUB check_rdb_error
                 EXIT FUNCTION Rdb$LU_STATUS
     &RDB&   END_ERROR
 
 
     &RDB&   GET
     &RDB&       ON ERROR
                     GOSUB check_rdb_error
                     EXIT FUNCTION Rdb$LU_STATUS
     &RDB&       END_ERROR
     &RDB&       sites = s.*
 
 
     &RDB&   END_GET
             vr_find_site_proc = 1%
     &RDB& END_FOR
             .
             .
             .

The error handlers used in these examples are shown in Section 4.2.5, ''Handling Errors''.

The examples in this section illustrate how to modify an existing record in a database using the MODIFY statement and how to store a new record in a database using the STORE statement.

                 .
                 .
                 .
 *
 * Obtain new customer ID number
 *
     &RDB& FOR i IN cu_id_inc_control
     &RDB&   ON ERROR
                 GO TO 900-rdb-error
     &RDB&   END_ERROR
 *
 * Retrieve next available ID number from control record
 *
     &RDB&   GET
     &RDB&       ON ERROR
                     GO TO 900-rdb-error
     &RDB&       END_ERROR
     &RDB&       customer_id = i.max_customer_id
     &RDB&   END_GET
 
 
 *
 * Increment next available ID number and update control record
 *
     &RDB&   MODIFY i USING
     &RDB&       ON ERROR
                     GO TO 900-rdb-error
     &RDB&       END_ERROR
     &RDB&       i.max_customer_id = i.max_customer_id + 1
     &RDB&   END_MODIFY
     &RDB& END_FOR
 
 
 
 *
 * Store new customer record
 *
     &RDB& STORE c IN customers USING
     &RDB&   ON ERROR
                 GO TO 900-rdb-error
     &RDB&   END_ERROR
     &RDB&   c.last_name = cu_last_name;
     &RDB&   c.first_name = cu_first_name;
 
 
                       .
                       .
                       .
     &RDB&   c.driver_license_region_id = 
     &RDB&                       cu_driver_license_region_id;
     &RDB&   c.driver_license_country_id =
     &RDB&                       cu_driver_license_country_id
     &RDB& END_STORE
              .
              .
              .
 

                 .
                 .
                 .
     !
     ! Obtain new customer ID number
     !
     &RDB& FOR i IN cu_id_inc_control
     &RDB&   ON ERROR
                 GOSUB check_rdb_error
                 EXIT FUNCTION Rdb$LU_STATUS
     &RDB&   END_ERROR
 
 
             !
             ! Retrieve next available ID number from control record
             !
     &RDB&   GET
     &RDB&       ON ERROR
                     GOSUB check_rdb_error
                     EXIT FUNCTION Rdb$LU_STATUS
     &RDB&       END_ERROR
     &RDB&       cust::customer_id = i.max_customer_id
     &RDB&   END_GET
 
 
             !
             ! Increment next available ID number and update record
             !
     &RDB&   MODIFY i USING
     &RDB&       ON ERROR
                     GOSUB check_rdb_error
                     EXIT FUNCTION Rdb$LU_STATUS
     &RDB&       END_ERROR
     &RDB&       i.max_customer_id = i.max_customer_id + 1%
     &RDB&   END_MODIFY
     &RDB& END_FOR
 
 
 
     !
     ! Store new customer record
     !
     &RDB& STORE c IN customers USING
     &RDB&   ON ERROR
                 GOSUB check_rdb_error
                 EXIT FUNCTION Rdb$LU_STATUS
     &RDB&   END_ERROR
 
 
     &RDB&   c.last_name = cust::cu_last_name;
     &RDB&   c.first_name = cust::cu_first_name;
                         .
                         .
                         .
 
 
     &RDB&   c.driver_license_region_id = 
     &rdb&                   cust::cu_driver_license_region_id;
     &RDB&   c.driver_license_country_id = 
     &rdb&                   cust::cu_driver_license_country_id
     &RDB& END_STORE
 

You typically write an error handler to process errors returned by Rdb when starting and ending a database transaction and when accessing data in the database. Handling error conditions using RDO with Rdb is very similar to using SQL with Rdb. This section describes the differences between RDO and SQL when using distributed transactions. See Section 4.1.6, ''Handling Errors'' for information on handling errors using SQL.

     EXTERNAL LONG CONSTANT RDB$_LOCK_CONFLICT           
                       .
                       .
                       .
     EXTERNAL LONG FUNCTION LIB$SIGNAL 
                       .
                       .
                       .
 
 
 check_rdb_error:
     SELECT Rdb$LU_STATUS
         CASE    RDB$_DEADLOCK,                                  &
                 RDMS$_DEADLOCK,                                 &
                 RDB$_LOCK_CONFLICT,                             &
                 RDMS$_LCKCNFLCT,                                &
                 RDMS$_TIMEOUT
             CALL ACMS$RAISE_TRANS_EXCEPTION( ACMS$_TRANSTIMEDOUT )
 
 
 
         CASE    RDB$_SYS_REQUEST_CALL,                          &
                 RDB$_BAD_TRANS_HANDLE,                          &
                 RDB$_DISTABORT,                                 &
                 RDB$_READ_ONLY_TRANS,                           &
                 RDB$_REQ_SYNC
             CALL ACMS$RAISE_TRANS_EXCEPTION( Rdb$LU_STATUS )
 
         CASE    ELSE
             CALL LIB$CALLG( Rdb$MESSAGE_VECTOR,                 &
                             LOC( LIB$SIGNAL ) BY VALUE )
             CALL ACMS$RAISE_NONREC_EXCEPTION( Rdb$LU_STATUS )
     END SELECT
     RETURN
        .
        .
        .
 

You use the RDO precompiler, RDBPRE, when you compile a procedure containing embedded RDO statements. The RDO precompiler processes the embedded RDO statements in your program, producing an intermediate host language source file, which it then submits to the host language compiler to produce an object module.

The RDO precompiler command line includes both precompiler and host language compiler qualifiers. For the precompiler, include a qualifier to specify in which host language the source is written; you can, optionally, include other qualifiers. On the command line, also include any language compiler qualifiers (such as LIST or DEBUG) that you want in effect when the precompiler submits the preprocessed source file to the language compiler. For more information on RDO precompiler qualifiers, see the Rdb documentation.

$ RCOB == "$RDBPRE/COBOL"

$ RCOB/LIST VR_FIND_SITE_RDO_PROC

Chapter 6, "Building Procedure Server Images" explains how to link procedures that use RDO.

COBOL supports DBMS DML statements as part of the COBOL language. However, if you are using DBMS with another language, such as BASIC, you use the DBMS DML precompiler to process the DML statements in your program in much the same way as you do when you use SQL or RDO with Rdb.

The DBMS DML precompiler uses a prefix character to distinguish DML statements from host language statements. The default prefix character is the pound-sign (#) character. For information on DML statements, refer to the DBMS documentation.

 DB  DEFAULT_SUBSCHEMA
     WITHIN "PERS_CDD.PERS_DBMS_SCHEMA"
     FOR "PERS_DB:PERS_DBMS".

     # INVOKE DEFAULT_SUBSCHEMA -
              WITHIN PERS_CDD.PERS_DBMS_SCHEMA -
              FOR PERS_DB:PERSONNEL -
              ( RECORDS )

The database and subschema you name must be the same in all the procedures linked into the server.

You start a DBMS database transaction by using a READY statement. However, the way in which you start the database transaction depends on whether the database transaction is part of a distributed transaction. In the READY statement, you can specify the realms the step procedure accesses in the database. If you do not specify one or more realms, DBMS readies all the realms in the subschema.

This section describes how to start a database transaction that is part of a distributed transaction and how to start and end an independent database transaction. In addition, it discusses various access modes that you can specify when starting a database transaction.

     CALL "DBQ$INTERPRET" USING
             BY DESCRIPTOR "READY CONCURRENT UPDATE FOR TRANSACTION",
             BY REFERENCE dist_tid
             GIVING return_status.
     IF return_status IS FAILURE
     THEN
         CALL "DBM$SIGNAL"
     END-IF

                .
                .
                .
     RECORD dist_tid_structure
         STRING tid_data = 16
     END RECORD
     DECLARE dist_tid_structure dist_tid
                .
                .
                .
     sts = ACMS$GET_TID( dist_tid BY REF )
 
     IF ( sts AND 1% ) = 0%                                      &
     THEN
         CALL ACMS$RAISE_NONREC_EXCEPTION( sts )
     END IF
 
     # READY CONCURRENT UPDATE FOR TRANSACTION dist_tid
                  .
                  .
                  .
 

     READY CONCURRENT RETRIEVAL.

     # READY CONCURRENT RETRIEVAL

       .
       .
       .
     IF sts IS SUCCESS
     THEN
         COMMIT
     ELSE
         ROLLBACK
     END-IF.
       .
       .
       .

        .
        .
        .
     IF ( sts AND 1% ) = 1%
     THEN
         # COMMIT
     ELSE
         # ROLLBACK
     END IF
        .
        .
        .

    LOGICAL NAME IS
         DBM$BIND_LOCK_TIMEOUT_INTERVAL = "10";
 

The examples in this section illustrate how to read a record from a DBMS database and return the data to the task in a workspace.

 IDENTIFICATION DIVISION.
 PROGRAM-ID. pers_find_employee_proc.
 
 
 ENVIRONMENT DIVISION.
 
 
 
 DATA DIVISION.
 SUB-SCHEMA SECTION.
 
 
 DB  DEFAULT_SUBSCHEMA
     WITHIN "PERS_CDD.PERS_DBMS_SCHEMA"
     FOR "PERS_DB:PERS_DBMS".
 
 
 WORKING-STORAGE SECTION.
 
 01 return_status                PIC S9(5) COMP.
 01 error_cond                   PIC S9(5) COMP.
 
 COPY "pers_files:pers_common_defns".
 
 
 
 LINKAGE SECTION.
 COPY "pers_cdd.employee_record" FROM DICTIONARY
     REPLACING ==employee_record== BY ==emp_wksp_record==.
 
 PROCEDURE DIVISION USING emp_wksp_record GIVING return_status.
 
 
 
 MAIN SECTION.
 
 000-start.
     MOVE emp_badge_number OF emp_wksp_record TO
          emp_badge_number OF employee_record.
 
     READY CONCURRENT RETRIEVAL.
 
     FETCH FIRST WITHIN ALL_EMPLOYEES 
                 USING emp_badge_number OF employee_record
 
 
     ON ERROR
         CALL "LIB$MATCH_COND" USING
                 BY REFERENCE DB-CONDITION,
                 BY REFERENCE DBM$_END,
                 BY REFERENCE DBM$_DEADLOCK,
                 BY REFERENCE DBM$_LCKCNFLCT,
                 BY REFERENCE DBM$_TIMEOUT
                 GIVING error_cond
 
 
         EVALUATE error_cond
             WHEN 1
                 MOVE persmsg_empnotfound TO return_status
             WHEN 2 THRU 4
                 MOVE persmsg_emplocked TO return_status
             WHEN OTHER
                 CALL "DBM$SIGNAL"
                 CALL "ACMS$RAISE_NONREC_EXCEPTION" USING
                             BY REFERENCE DB-CONDITION
         END-EVALUATE
 
 
     NOT ON ERROR
         MOVE employee_record TO emp_wksp_record
         MOVE persmsg_success TO return_status
     END-FETCH.
 
     COMMIT.
 
 999-end.
     EXIT PROGRAM.
 

Example 4.9, ''Step Procedure in BASIC that Reads a DBMS Record'' illustrates a simple step procedure written in BASIC that reads a record from a personnel database. The procedure extends the previous COBOL example by including logic to retry the transaction automatically if the employee's record is locked. The procedure first initializes a transaction retry-counter and moves the record key from the task workspace into the user work area (UWA). It then starts a database transaction, reads the record from the database, and ends the transaction. Finally, the procedure moves the employee's record from the UWA into the task workspaces and returns a success status.

     FUNCTION LONG pers_find_employee_proc( employee_record emp_wksp )
 
     OPTION HANDLE=SEVERE
 
     %INCLUDE "pers_files:pers_common_defns"
     %INCLUDE %FROM %CDD "pers_cdd.employee_record"
 
 
 
     DECLARE LONG retry_count
 
     # INVOKE DEFAULT_SUBSCHEMA -
              WITHIN PERS_CDD.PERS_DBMS_SCHEMA -
              FOR PERS_DB:PERS_DBMS -
              ( RECORDS )
 
 
 
     WHEN ERROR IN
         retry_count = 0%
         employee_record::emp_badge_number = emp_wksp::emp_badge_number
 
 
 
 start_db_trans:
         # READY CONCURRENT RETRIEVAL
         # FETCH FIRST WITHIN ALL_EMPLOYEES USING emp_badge_number
         # COMMIT
 
         emp_wksp = employee_record
         pers_find_employee_proc = persmsg_success
 
 
     USE
         SELECT LIB$MATCH_COND( DBM_COND, DBM$_END,                      &
                                          DBM$_DEADLOCK,                 &
                                          DBM$_LCKCNFLCT,                &
                                          DBM$_TIMEOUT )
             CASE 1          ! DBM$_END
                 pers_find_employee_proc = persmsg_empnotfound
 
 
 
             CASE 2, 3, 4    ! DBM$_DEADLOCK, DBM$_LCKCNFLCT, DBM$_TIMEOUT
                 IF retry_count < 5%                                     &
                 THEN
                     retry_count = retry_count + 1%
                     # ROLLBACK ( TRAP ERROR )
                     CONTINUE start_db_trans
                 ELSE
                     pers_find_employee_proc = persmsg_emplocked
                 END IF
 
 
 
             CASE ELSE
                 EXIT HANDLER
         END SELECT
         # ROLLBACK ( TRAP ERROR )
     END WHEN
 
     END FUNCTION
 

This section illustrates how to store a new record in a DBMS database and how to update a record in a DBMS database.

Example 4.10, ''Step Procedure in COBOL that Updates a DBMS Record'' explains how to store a new record in a DBMS database. The PERS_ADD_EMPLOYEE_PROC procedure stores a new record in the employee set using the information that is entered by the user and passed to the procedure in a task workspace.

 IDENTIFICATION DIVISION.
 PROGRAM-ID. pers_add_employee_proc.
 
 ENVIRONMENT DIVISION.
 
 DATA DIVISION.
 SUB-SCHEMA SECTION.
 
 
 
 DB  DEFAULT_SUBSCHEMA
     WITHIN "PERS_CDD.PERS_DBMS_SCHEMA"
     FOR "PERS_DB:PERS_DBMS".
 
 
 
 WORKING-STORAGE SECTION.
 
 01 return_status                PIC S9(5) COMP.
 01 error_cond                   PIC S9(5) COMP.
 01 dist_tid.
    03 tid_data                  PIC X(16).
 
 
 
 COPY "pers_files:pers_common_defns".
 
 LINKAGE SECTION.
 COPY "pers_cdd.employee_record" FROM DICTIONARY
     REPLACING ==employee_record== BY ==emp_wksp_record==.
 
 
 
 PROCEDURE DIVISION USING emp_wksp_record GIVING return_status.
 
 DECLARATIVES.
 dml-failure SECTION.
     USE FOR DB-EXCEPTION.
 010-dbm-failure.
         .
         .
         .
     EXIT PROGRAM.
 END DECLARATIVES.
 
 
     
 MAIN SECTION.
 
 000-start.
     CALL "ACMS$GET_TID" USING 
                 BY REFERENCE dist_tid
                 GIVING return_status.
     IF return_status IS FAILURE
     THEN
         CALL "ACMS$RAISE_NONREC_EXCEPTION" USING
                 BY REFERENCE return_status
         EXIT PROGRAM
     END-IF.
 
 
 
     CALL "DBQ$INTERPRET" USING
             BY DESCRIPTOR "READY CONCURRENT UPDATE FOR TRANSACTION",
             BY REFERENCE dist_tid
             GIVING return_status.
     IF return_status IS FAILURE
     THEN
         CALL "DBM$SIGNAL"
     END-IF
 
 
     
     MOVE emp_wksp_record TO employee_record.
     CALL "SYS$GETTIM" USING 
             BY REFERENCE emp_last_update OF employee_record
             GIVING return_status.
     IF return_status IS FAILURE
     THEN
         CALL "LIB$STOP" USING BY VALUE return_status
     END-IF.
 
     STORE employee_record.
 
     MOVE persmsg_success TO return_status.
 
 999-end.
     EXIT PROGRAM.
 

Example 4.11, ''Step Procedure in BASIC that Updates a DBMS Record'' illustrates how to update a record in a DBMS database. The PERS_CHANGE_EMPLOYEE_PROC procedure updates a record in the employee set using the information that is entered by the user and passed to the procedure in a task workspace. To conserve resources, the task does not retain server context while the user is modifying the employee's information. Therefore, the procedure must ensure that the information in the record has not changed while the user was updating the information on the screen.

     FUNCTION LONG pers_change_employee_proc( employee_record emp_wksp )
 
     OPTION HANDLE=SEVERE
 
     %INCLUDE "pers_files:pers_common_defns"
     %INCLUDE %FROM %CDD "pers_cdd.employee_record"
 
 
 
     RECORD dist_tid_structure
         STRING tid_data = 16
     END RECORD
     DECLARE dist_tid_structure dist_tid
 
     DECLARE LONG sts
 
 
 
     # INVOKE DEFAULT_SUBSCHEMA -
              WITHIN PERS_CDD.PERS_DBMS_SCHEMA -
              FOR PERS_DB:PERS_DBMS -
              ( RECORDS )
 
 
 
     sts = ACMS$GET_TID( dist_tid BY REF )
     IF ( sts AND 1% ) = 0%                                              &
     THEN
         CALL ACMS$RAISE_NONREC_EXCEPTION( sts )
     END IF
 
 
 
     WHEN ERROR IN
         employee_record::emp_badge_number = emp_wksp::emp_badge_number
         # READY CONCURRENT UPDATE FOR TRANSACTION dist_tid
         # FETCH FIRST WITHIN ALL_EMPLOYEES -
                       USING emp_badge_number
         IF employee_record::emp_last_update =                           &
            emp_wksp::emp_last_update                                    &
         THEN
             employee_record = emp_wksp
             sts = SYS$GETTIM( employee_record::emp_last_update BY REF )
             IF ( sts AND 1% ) = 0%                                      &
             THEN
                 CALL LIB$STOP( sts )
             END IF
             # MODIFY employee_record
             pers_change_employee_proc = persmsg_success
         ELSE
             pers_change_employee_proc = persmsg_empchanged
         END IF
 
 
     USE
        .
        .
        .
     END WHEN
 
     END FUNCTION
 

You typically write an error handler to process errors returned by DBMS when accessing records in a database. The examples in Section 4.3.3, ''Reading from a Database'' and Section 4.3.4, ''Writing to a Database'' illustrate how to handle some of the standard errors, such as record-not-found, that DBMS can return when you read, write, or update a record in a database. In addition, also be aware of the error conditions that can occur when you are using DBMS in distributed transactions.

Some DBMS errors are expected and are handled by resuming normal program execution. For example, DBMS returns an end-of-collection error if a procedure reads past the last record in a set. In this case, the program can resume execution and process the records that have been read. DBMS can also return a number of recoverable errors that the program should check for and handle. For example, if DBMS returns a deadlock error, you might want to roll back the transaction and process the transaction again. Finally, DBMS can return a number of nonrecoverable errors. For example, a disk on which one of the database storage areas resides might fail. In this case, the program cannot continue until the problem has been resolved.

A distributed transaction can abort at any time. If a transaction aborts while a step procedure is executing, DBMS automatically rolls back an active database transaction. However, the step procedure will receive an error the next time it executes a DML statement in a database transaction that was participating in the distributed transaction. Therefore, an error handler for a step procedure should check for and handle the errors that DBMS returns in this situation.

Typically, you want to retry a transaction automatically in the event of a recoverable error condition such as a deadlock, lock-timeout or transaction timeout error. If DBMS detects deadlock or lock-timeout error conditions, it returns an error to your step procedure when you access the database. In contrast, if a distributed transaction times out, the distributed transaction is aborted, and ACMS raises a transaction exception in the task. In this case, DBMS returns an error if the step procedure accesses the file after the transaction has aborted.

        .
        .
        .
 WORKING-STORAGE SECTION.
 
 01 return_status                PIC S9(5) COMP.
 01 error_cond                   PIC S9(5) COMP.
 01 dist_tid.
    03 tid_data                  PIC X(16).
        .
        .
        .
 PROCEDURE DIVISION USING emp_wksp_record GIVING return_status.
 
 
 
 DECLARATIVES.
 dml-failure SECTION.
     USE FOR DB-EXCEPTION.
 
 
 010-dbm-failure.
     CALL "LIB$MATCH_COND" USING
                 BY REFERENCE DB-CONDITION,
                 BY REFERENCE DBM$_DUPNOTALL,
                 BY REFERENCE DBM$_DEADLOCK,
                 BY REFERENCE DBM$_LCKCNFLCT,
                 BY REFERENCE DBM$_TIMEOUT,
                 BY REFERENCE DBM$_PARTDTXNERR,
                 BY REFERENCE DBM$_NOTIP,
                 BY REFERENCE DBM$_DTXNABORTED
                 GIVING error_cond
 
 
     EVALUATE error_cond
         WHEN 1
             MOVE persmsg_empexists TO return_status
         WHEN 2 THRU 4
             CALL "ACMS$RAISE_TRANS_EXCEPTION" USING
                             BY REFERENCE ACMS$_TRANSTIMEDOUT
         WHEN 5 THRU 7
             CALL "ACMS$RAISE_TRANS_EXCEPTION" USING
                             BY REFERENCE DB-CONDITION
         WHEN OTHER
             CALL "DBM$SIGNAL"
             CALL "ACMS$RAISE_NONREC_EXCEPTION" USING
                             BY REFERENCE DB-CONDITION
 
 
     END-EVALUATE
     EXIT PROGRAM.
 END DECLARATIVES.
        .
        .
        .
 

        .
        .
        .
     WHEN ERROR IN
         employee_record::emp_badge_number = emp_wksp::emp_badge_number
         # READY CONCURRENT UPDATE FOR TRANSACTION dist_tid
         # FETCH FIRST WITHIN ALL_EMPLOYEES -
                       USING emp_badge_number
 
 
         IF employee_record::emp_last_update =                           &
            emp_wksp::emp_last_update                                    &
         THEN
             employee_record = emp_wksp
             sts = SYS$GETTIM( employee_record::emp_last_update BY REF )
             IF ( sts AND 1% ) = 0%                                      &
             THEN
                 CALL LIB$STOP( sts )
             END IF
             # MODIFY employee_record
             pers_change_employee_proc = persmsg_success
 
 
         ELSE
             pers_change_employee_proc = persmsg_empchanged
         END IF
 
 
     USE
         SELECT LIB$MATCH_COND( DBM_COND, DBM$_END,                      &
                                          DBM$_DEADLOCK,                 &
                                          DBM$_LCKCNFLCT,                &
                                          DBM$_TIMEOUT,                  &
                                          DBM$_PARTDTXNERR,              &
                                          DBM$_NOTIP,                    &
                                          DBM$_DTXNABORTED )
 
 
             CASE 1          ! DBM$_END
                 pers_change_employee_proc = persmsg_empdeleted
 
             CASE 2, 3, 4    ! DBM$_DEADLOCK, DBM$_LCKCNFLCT, DBM$_TIMEOUT
                 CALL ACMS$RAISE_TRANS_EXCEPTION( ACMS$_TRANSTIMEDOUT )
 
             CASE 5, 6, 7    ! DBM$_PARTDTXNERR, DBM$_NOTIP, DBM$_DTXNABORTED
                 CALL ACMS$RAISE_TRANS_EXCEPTION( VMSSTATUS  )
 
 
                 
             CASE ELSE
                 EXIT HANDLER
         END SELECT
     END WHEN
        .
        .
        .
 

If you are using COBOL, use the COBOL compiler to compile your procedure. However, if you are using another programming language, such as BASIC, use the DBMS DML precompiler when you compile a procedure containing embedded DML statements. The DML precompiler processes the embedded DML statements in your program, producing an intermediate host language source file, which it then submits to the host language compiler to produce an object module.

The DML precompiler command line includes both precompiler and host language compiler qualifiers. For the precompiler, use the /LANGUAGE qualifier to specify in which host language the source is written; you can, optionally, include other qualifiers. On the command line, include any language compiler qualifiers (such as LIST or DEBUG) that you want in effect when the precompiler submits the preprocessed source file to the language compiler using the /OPTION qualifier. For more information on DML precompiler qualifiers, see the DBMS documentation.

$ DML/LANGUAGE=BASIC/OPTION="/LIST" PERS_CHANGE_EMPLOYEE_PROC

Chapter 6, "Building Procedure Server Images" explains how to link procedures that use DML.

In contrast, if you access an RMS file marked for recovery-unit journaling outside a distributed transaction, you must start a transaction in the step procedure. Use the OpenVMS transactions services $START_TRANS, $END_TRANS, and $ABORT_TRANS to start and end a transaction in a step procedure. Note that the OpenVMS transaction services have superseded the RMS Recovery Unit services. See RMS Journaling for OpenVMS Manual for more information on using the OpenVMS transaction services and RMS recovery-unit journaling.

The examples in this section illustrate how to read a record from an RMS file and return the data to the task in a workspace.

Each example reads a record from a file containing employee records using a key from a field in a workspace. If the record exists, the procedure returns a success status to the task. If the record does not exist, the procedure returns a failure status. Because the PERS_FIND_EMPLOYEE_PROC procedure executes in a server that opens the employee file for read-only access, there is no need to use manual locking statements.

 IDENTIFICATION DIVISION.
 PROGRAM-ID. pers_find_employee_proc.
        .
        .
        .
 DATA DIVISION.
 
 
 FILE SECTION.
 FD      emp_file
         EXTERNAL
         DATA RECORD IS employee_record
         RECORD KEY emp_badge_number OF employee_record.
 COPY "pers_cdd.employee_record" FROM DICTIONARY.
        .
        .
        .
 
 
 LINKAGE SECTION.
 COPY "pers_cdd.employee_record" FROM DICTIONARY
     REPLACING ==employee_record== BY ==emp_wksp_record==.
 
 PROCEDURE DIVISION USING emp_wksp_record GIVING return_status.
 MAIN SECTION.
 
 
 
 000-start.
     MOVE persmsg_success TO return_status.
     MOVE emp_badge_number OF emp_wksp_record TO
          emp_badge_number OF employee_record.
     READ emp_file RECORD INTO emp_wksp_record
         KEY IS emp_badge_number OF employee_record
         INVALID KEY
             MOVE persmsg_empnotfound TO return_status
             GO TO 999-end
     END-READ.
 
 
        .
        .
        .
 999-end.
     EXIT PROGRAM.
 

     FUNCTION LONG pers_find_employee_proc( employee_record emp_wksp )
 
     %INCLUDE "pers_files:pers_common_defns"
     %INCLUDE %FROM %CDD "pers_cdd.employee_record"
 
 
 
     MAP ( emp_map ) employee_record emp_rec
 
 
     WHEN ERROR IN
         GET # emp_file,                                         &
             KEY # 0 EQ emp_wksp::emp_badge_number
         MOVE FROM # emp_file, emp_wksp
         pers_find_employee_proc = persmsg_success
 
 
     USE
         SELECT ERR
             CASE basicerr_record_not_found
                 pers_find_employee_proc = persmsg_empnotfound
             CASE ELSE
                 CALL ACMS$RAISE_NONREC_EXCEPTION( RMSSTATUS( emp_file ) )
                 EXIT HANDLER
         END SELECT
     END WHEN
 
     END FUNCTION
 

This section explains how to write a new record into an RMS file and how to update a record in an RMS file.

 IDENTIFICATION DIVISION.
 PROGRAM-ID. pers_add_employee_proc.
 
        .
        .
        .
 DATA DIVISION.
 
 
 FILE SECTION.
 FD      emp_file
         EXTERNAL
         DATA RECORD IS employee_record
         RECORD KEY emp_badge_number OF employee_record.
 
 
 COPY "pers_cdd.employee_record" FROM DICTIONARY.
        .
        .
        .
 
 
 LINKAGE SECTION.
 COPY "pers_cdd.employee_record" FROM DICTIONARY
     REPLACING ==employee_record== BY ==emp_wksp_record==.
 
 
 
 PROCEDURE DIVISION USING emp_wksp_record GIVING return_status.
 MAIN SECTION.
 
 
 
 000-start.
     CALL "SYS$GETTIM" USING 
             BY REFERENCE emp_last_update OF emp_wksp_record
             GIVING return_status.
     IF return_status IS FAILURE
     THEN
         CALL "LIB$STOP" USING BY VALUE return_status
     END-IF.
 
 
     MOVE persmsg_success TO return_status.
     WRITE employee_record FROM emp_wksp_record
         ALLOWING NO
         INVALID KEY
             MOVE persmsg_empexists TO return_status
         NOT INVALID KEY
             UNLOCK emp_file ALL RECORDS
     END-WRITE.
        .
        .
        .
 999-end.
     EXIT PROGRAM.
 

Example 4.15, ''Step Procedure in BASIC that Updates an RMS Record'' illustrates how to update a record in an RMS file. The PERS_CHANGE_EMPLOYEE_PROC procedure updates a record in an employee file using the information that is entered by the user and passed to the procedure in a task workspace. To conserve resources, the task does not retain server context while the user is modifying the employee's information. Therefore, the procedure must ensure that the information in the record has not changed while the user was updating the information on the screen.

The procedure first rereads the original record in the file and then uses a time-stamp stored in the record to ensure that the version read in this procedure is the same as the version read previously by the PERS_FIND_EMPLOYEE_PROC procedure. If the record has been updated, the procedure returns an error and unlocks the record. If the record has not been changed, the procedure copies the data from the task workspace record to the file record, calls SYS$GETTIM to retrieve the current system time, and updates the current record.

     FUNCTION LONG pers_change_employee_proc( employee_record emp_wksp )
 
     %INCLUDE "pers_files:pers_common_defns"
     %INCLUDE %FROM %CDD "pers_cdd.employee_record"
 
 
 
     DECLARE LONG sts
 
     MAP ( emp_map ) employee_record emp_rec
 
 
 
     WHEN ERROR IN
         GET # emp_file,                                         &
             KEY # 0 EQ emp_wksp::emp_badge_number,              &
             ALLOW NONE,                                         &
             WAIT 20
         IF emp_rec::emp_last_update = emp_wksp::emp_last_update &
 
 
         THEN
             MOVE TO # emp_file, emp_wksp
             sts = SYS$GETTIM( emp_rec::emp_last_update BY REF )
             IF ( sts AND 1% ) = 0%                              &
             THEN
                 CALL LIB$STOP( sts )
             END IF
             UPDATE # emp_file
             pers_change_employee_proc = persmsg_success
 
 
         ELSE
             pers_change_employee_proc = persmsg_empchanged
         END IF
         UNLOCK # emp_file
 
 
     USE
         SELECT ERR
             CASE    basicerr_record_not_found
                 pers_change_employee_proc = persmsg_empdeleted
             CASE    basicerr_record_locked,                             &
                     basicerr_deadlock,                                  &
                     basicerr_wait_exhausted
                 pers_change_employee_proc = persmsg_emplocked
             CASE    ELSE
                 CALL ACMS$RAISE_NONREC_EXCEPTION( RMSSTATUS( emp_file ) )
                 EXIT HANDLER
         END SELECT
     END WHEN
 
     END FUNCTION
 

You typically write an error handler to process errors returned by RMS when accessing records in a file. The examples in Section 4.4.2, ''Reading RMS Records'' and Section 4.4.3, ''Writing and Updating RMS Records'' illustrate how to handle some standard errors, such as record-not-found, that RMS can return when you read, write, or update a record in an RMS file. In addition, also be aware of the error conditions that can occur when you use RMS files in distributed transactions.

Some RMS errors are expected and are handled by resuming normal program execution. For example, RMS returns an end-of-file error if a procedure reads past the last record in a file. In this case, the program can resume execution and process the records that have been read. RMS can also return a number of recoverable errors that the program should check for and handle. For example, if RMS returns a deadlock error, you might want to roll back the transaction and process the transaction again. Finally, RMS can return a number of nonrecoverable errors. For example, a disk on which a file resides might fail. In this case, the program cannot continue until the problem has been resolved.

A distributed transaction can abort at any time. For example, if the PERS_CHANGE_EMPLOYEE_PROC procedure shown in Section 4.4.3, ''Writing and Updating RMS Records'' participates in a distributed transaction, the transaction could time out while the procedure is reading the original copy of the employee's record or while updating the record with the new information. If a transaction aborts while a step procedure is executing, RMS automatically rolls back an active recovery unit. If a step procedure reads a record from the file after a distributed transaction has aborted, RMS completes the operation successfully if the record exists and is not locked by another process. However, the step procedure receives an error if it executes a recoverable operation, such as a write or update operation, on the file. Therefore, an error handler for a step procedure should check for and handle the errors that RMS returns in this situation.

If you use RMS in a distributed transaction, you must write a server cancel procedure to release any records that might be read and locked by a step procedure after a distributed transaction aborts. See Chapter 2, "Writing Initialization, Termination, and Cancel Procedures" for more information on writing server cancel procedures.

Typically, you want to retry a transaction automatically in the event of a recoverable error condition such as a deadlock, lock-timeout or transaction timeout error. RMS returns deadlock and lock-timeout errors to your step procedure when you access the file. In contrast, if a distributed transaction times out, the distributed transaction is aborted, and ACMS raises a transaction exception in the task. In this case, RMS returns an error if the step procedure accesses the file after the transaction has aborted.

    .
    .
    .
 PROCEDURE DIVISION USING emp_wksp_record GIVING return_status.
 
 
 
 DECLARATIVES.
 employee_file SECTION.
     USE AFTER STANDARD ERROR PROCEDURE ON emp_file.
 
 
 employee_file_handler.
     EVALUATE TRUE
         WHEN    ( ( RMS-STS OF emp_file = RMS$_RLK ) OR
                   ( RMS-STS OF emp_file = RMS$_DEADLOCK ) )
             CALL "ACMS$RAISE_TRANS_EXCEPTION" USING
                         BY REFERENCE ACMS$_TRANSTIMEDOUT
         WHEN    ( ( RMS-STS OF emp_file = RMS$_NRU ) OR
                   ( RMS-STS OF emp_file = RMS$_DDTM_ERR ) )
             CALL "ACMS$RAISE_TRANS_EXCEPTION" USING
                         BY REFERENCE RMS-STS OF emp_file
 
 
         WHEN    OTHER
             CALL "LIB$SIGNAL" USING
                         BY REFERENCE RMS-STS OF emp_file,
                         BY REFERENCE RMS-STV OF emp_file
             CALL "ACMS$RAISE_NONREC_EXCEPTION" USING
                         BY REFERENCE RMS-STS OF emp_file
     END-EVALUATE.
 END DECLARATIVES.
 
 
 
 MAIN SECTION.
 000-start.
     MOVE persmsg_success TO return_status.
 
 
 
     MOVE emp_badge_number OF emp_wksp_record TO
          emp_badge_number OF employee_record.
     READ emp_file RECORD
         ALLOWING NO OTHERS
         KEY IS emp_badge_number OF employee_record
         INVALID KEY
             MOVE persmsg_empdeleted TO return_status
             GO TO 999-end
     END-READ.
 
 
 
     IF emp_last_update OF employee_record = emp_last_update OF emp_wksp_record
     THEN
         CALL "SYS$GETTIM" USING 
                 BY REFERENCE emp_last_update OF emp_wksp_record
                 GIVING return_status
         IF return_status IS FAILURE
         THEN
             CALL "LIB$STOP" USING BY VALUE return_status
         END-IF
 
 
         REWRITE employee_record FROM emp_wksp_record
             ALLOWING NO OTHERS
             INVALID KEY
                 CALL "ACMS$RAISE_NONREC_EXCEPTION"
                             USING RMS-STS OF emp_file
         END-REWRITE
 
 
     ELSE
         MOVE persmsg_empchanged TO return_status
     END-IF.
 
     UNLOCK emp_file ALL RECORDS.
 
 999-end.
     EXIT PROGRAM.

     FUNCTION LONG pers_change_employee_proc( employee_record emp_wksp )
 
     %INCLUDE "pers_files:pers_common_defns"
     %INCLUDE %FROM %CDD "pers_cdd.employee_record"
 
 
 
     DECLARE LONG sts
 
     MAP ( emp_map ) employee_record emp_rec
 
 
 
     WHEN ERROR IN
         GET # emp_file,                                         &
             KEY # 0 EQ emp_wksp::emp_badge_number,              &
             ALLOW NONE,                                         &
             WAIT 20
         IF emp_rec::emp_last_update = emp_wksp::emp_last_update &
         THEN
             MOVE TO # emp_file, emp_wksp
             sts = SYS$GETTIM( emp_rec::emp_last_update BY REF )
             IF ( sts AND 1% ) = 0%                              &
             THEN
                 CALL LIB$STOP( sts )
             END IF
             UPDATE # emp_file
             pers_change_employee_proc = persmsg_success
 
 
         ELSE
             pers_change_employee_proc = persmsg_empchanged
         END IF
         UNLOCK # emp_file
 
 
     USE
         SELECT ERR
             CASE    basicerr_record_not_found
                 pers_change_employee_proc = persmsg_empdeleted
             CASE    basicerr_record_locked,                             &
                     basicerr_deadlock,                                  &
                     basicerr_wait_exhausted
                 CALL ACMS$RAISE_TRANS_EXCEPTION( ACMS$_TRANSTIMEDOUT )
 
 
             CASE    ELSE
                 IF ( RMSSTATUS( emp_file ) = RMS$_NRU ) OR              &
                    ( RMSSTATUS( emp_file ) = RMS$_DDTM_ERR )            &
                 THEN
                     CALL ACMS$RAISE_TRANS_EXCEPTION( RMSSTATUS( emp_file ) )
                 ELSE
                     CALL ACMS$RAISE_NONREC_EXCEPTION( RMSSTATUS( emp_file ) )
                     EXIT HANDLER
                 END IF
         END SELECT
     END WHEN
 
     END FUNCTION

The .TITLE statement defines the object module name, which is assigned to the object module when you compile the source file using the Message Utility. The object module does not need to have the same name as the source file or the file containing the object module, but it is common practice to do so. The maximum length of the module name is 31 characters.

 .TITLE VRMSG Messages for AVERTZ 

After the module name (here, VRMSG) is a listing title. If you use the /LIST qualifier when compiling the source file, the listing title (in this case, Messages for AVERTZ), appears at the top of each page of the .LIS file. The maximum length of a listing title is 28 characters.

 .IDENT /Version 1.0/

The Message Utility includes the literal string from the .IDENT statement in the object module name.

 ! History:
 !           V1.0    Created 12-May-91.

Comment text helps others understand the message file and documents the history of the file.

The following sections explain how to write these.

 .FACILITY VR,1
   .
   .
   .
 .END

 .FACILITY VR,1
 .SEVERITY INFORMATION
   .
   .
   .
 .END

 .TITLE VRMSG Messages for AVERTZ 
 .IDENT /Version 1.0/
 
 .FACILITY VR,1 /PREFIX=VR_
 
 
 .SEVERITY INFORMATION
 MULCURECFND <Multiple customer records found>
 MULRSRECFND <Multiple reservation records found>
 VEUPGPRF    <Vehicle upgrade performed - no charge>
 VEDNGPRF    <Vehicle downgrade performed - rates adjusted>
 CURECUPD    <Customer record has been updated in database-hit RETURN to continue>
 CURECINS    <Customer record has been inserted in database>
 CHKINCOMP   <Vehicle Checking-in completed successfully - hit RETURN to continue>
 CHKOUTCOM   <Vehicle Checkout completed successfully - hit RETURN to continue>
 RESVCOMP    <Vehicle reservation completed successfully - hit RETURN to continue>
 VERECFND    <Vehicles/vehicles found in class requested, choose one>
 RESSUCCNCLD <Reservation successfully canceled - hit RETURN to continue>
 
 
 .SEVERITY WARNING
 CURECNOTFND  <Customer record not found>
 RCRECNOTFND  <Rental class record not found>
 RERECNOTFND  <Invalid state/country-reenter valid state/country names>
 RSRECNOTFND  <Reservation record not found >
 SIRECNOTFND  <Site record not found, press PF1 S for a list of sites>
 VERECNOTFND  <No vehicles available for checkout - hit RETURN to continue>
 VRHRECNOTFND <Vehicle rental history record not found>
 NOTCHKOUT    <Vehicle not checked out>
 RESCNCLD     <Reservation was canceled - reenter data or PF1 Q to quit>
 CARCHKIN     <Reservation archived,car checked in,paid in full>
 CARCHKOUT    <Vehicle has already been checked out - reenter data or PF1 Q to quit>
 RESCLOSED    <Reservation archived,car checked in,payment pending>
 DLRENOTFND   <Invalid Driver's license state/country>
 NOCANCEL     <Reservation cannot be canceled at this stage>
 INACTIVE     <Please enter data or task will be canceled due to inactivity>
 DDTM_TIMEOUT <The distributed transaction timed out --- please retry>
 
 
 .SEVERITY ERROR
 NO_DUP           <Duplicate database key>
 DEADLOCK         <Database deadlock>
 INTEG_FAIL       <Database integrity failure>
 LOCK_CONFLICT    <Database lock conflict>
 CAR_UNAVAILABLE  <Vehicle unavailable - hit RETURN to continue>
 CHK_CANCL_ERR    <Error in checkout or cancel reservation>
 HIST_WRITE_ERR   <Error in writing to history file>
 UPDATE_ERROR     <Error updating file>
 
 
 .SEVERITY FATAL
 BILLERR          <Bill computation error - canceling transaction>
 DB_FATAL         <Fatal database error - check audit log>
 ICRECNOTFND      <ID increment control record not found>
 
 .END

Follow the instructions in Chapter 3, "Writing Step Procedures" for writing step procedures. Follow the instructions in Chapter 2, "Writing Initialization, Termination, and Cancel Procedures" for writing initialization, termination, and cancel procedures.

Compiling step, initialization, termination, and cancel procedures is similar to compiling any program. You use the same commands, create the same output files, and expect the same kinds of errors, such as missing periods in COBOL or missing ampersands in BASIC. For information on compiling source programs and correcting compile-time errors, see the reference manual and user's guide for the language you are using.

$ COBOL/DEBUG VR_FIND_SI_PROC

The file name of the procedure in the example is VR_FIND_SI_PROC.

Figure 6.2, ''Compiling Source Code into Object Modules'' shows the relationship between procedure source files and their file names when they are compiled to create object modules. These are the file names that you use when you link object modules in step 5. The example uses COBOL step, initialization, and termination procedures from the AVERTZ application.

Chapter 5, "Using Message Files with ACMS Tasks and Procedures" explains how to create, compile, and link message files. When you use the Message Utility a second time, you create a pointer object module, which is a file that you link into the procedure server image in step 5.

ADU> BUILD GROUP VR_TASK_GROUP

VSI ACMS for OpenVMS Writing Applications contains detailed instructions for building a task group.

ADU> BUILD GROUP VR_TASK_GROUP/DEBUG

Chapter 7, "Debugging Tasks and Procedures" contains instructions for debugging tasks.

Link the object code of procedures with the procedure server transfer module into a procedure server image. Before linking, you can place files in a procedure object library. Doing so allows you to track insertion into the library and simplifies the job of creating a server image. Using procedure object libraries also reduces linking time. See Section 6.2, ''Using an Object Library for Procedures'' for more information about using an object library.

Figure 6.3, ''Linking Object Modules into a Procedure Server Image'' shows the relationship between the task group definition and object modules when they are linked to create a procedure server image.

$ LINK/DEBUG/EXE=VR_SERVER.EXE VR_SERVER.OBJ,-
_$ ACMS$SAMPLES:VR_TERM,- 
_$ ACMS$SAMPLES:VR_GET_CUSTOMER_PROC,-
_$ ACMS$SAMPLES:VR_MOVE_CU_PROC,-
_$ ACMS$SAMPLES:VR_INIT,-
_$ SYS$LIBRARY:SQL$USER/LIB

When linking a server image containing procedures called by tasks that use the WITH SQL RECOVERY phrase, you must reference the ACMS SQL library in SYS$LIBRARY immediately after the transfer vector object module name. As the last item, link the SQL library file that is found in SYS$LIBRARY. When you use the WITH SQL RECOVERY phrase in the task definition, if you do not reference the correct libraries in the correct order, you can receive unpredictable run-time errors.

$ LINK/DEBUG/EXE=VR_SERVER.EXE VR_SERVER.OBJ,-
_$ SYS$LIBRARY:ACMSSQL/LIB,-
_$ ACMS$SAMPLES:VR_GET_CUSTOMER_PROC,-
_$ ACMS$SAMPLES:VR_MOVE_CU_PROC,-
_$ ACMS$SAMPLES:VR_INIT,-
_$ SYS$LIBRARY:SQL$USER/LIB

The ACMSSQL library is not required if the SQL database transactions are started by the step procedures in the server, not in the task definition.

 PSECT_ATTR=RDB$TRANSACTION_HANDLE,LCL,NOSHR
 PSECT_ATTR=RDB$DBHANDLE,LCL,NOSHR

Because of an Rdb restriction, the link is not upward compatible; therefore, you need to relink the server for each new version of Rdb.

$ COBOL/DEBUG VR_FIND_SI_PROC
 $ LINK/DEBUG/EXE=VR_SERVER.EXE VR_SERVER.OBJ,-
 .
 .
 .

After you compile and link the procedures called by a task, you can run the task in the ACMS Task Debugger. The task you run is a real one; when the task is in daily use, ACMS runs the same definitions and code as the ones you test.

To protect business data, you can set up test files to run against the task. For example, if your procedures use logical names to identify files, create a set of data files in another directory, and temporarily redefine the logical names to point to that directory. See Section 7.2.3, ''Defining Logical Names'' for an explanation of the two methods of defining logical names.

One of the difficult parts of debugging a task is making sure that all the files you need are complete. Chapter 6, "Building Procedure Server Images" explains the steps you take to build a procedure server image. After completing those steps, check that all the files are ready. Figure 7.1, ''Files Needed for Debugging'' shows the files needed for debugging and depicts how you produce those files from CDD definitions, source programs, and message source files.

Most task groups and server procedures use OpenVMS logical names. If this is the case in your ACMS application, you must define these logical names before you start a debugging session. For example, the AVERTZ task group definition specifies that it uses the message file AVERTZ_DEFAULT:VRMSG.EXE. If the logical name AVERTZ_DEFAULT is not defined when you attempt to start the debugging session, the Task Debugger cannot find the message file, and therefore cannot start.

Some of the logical names used by your task group and server procedures might have already been defined. In the previous example, the AVERTZ application might be installed on your system in such a way that the necessary logical names are available to everyone on the system. In this case, you do not need to define any logical names in order to run the application. However, if the logical names are not defined, or if you want to test your own private copy of a file, you must define the logical names that point to that file. Also, be sure to define logical names in a way that does not affect other users on the system.

To define logical names, you need some information about the processes that are used in a debugging session. When you use the ACMS/DEBUG task-group command, you run the ACMS Task Debugger image in your process. For this reason, any logical names that are available to your process are also available to the Task Debugger.

However, when the Task Debugger starts a server, it creates the server as a subprocess of your process. When this server process is created, it has access to the same logical name tables as the Task Debugger process, with the exception of the Task Debugger's process logical name table. Instead of using the Task Debugger process logical name table, each server is created with its own process logical name table.

See VSI OpenVMS User's Manual for more information on logical names and logical name tables.

If exchange steps in your tasks call DECforms, and DECforms, in turn, calls procedural escapes, you need to debug escape routines. Because DECforms escape routines are written in an OpenVMS programming language, you use the OpenVMS Debugger to debug escape routines. To have more information available to you while you are debugging, compile escape routines using the /DEBUG qualifier.

You must complete several preparatory steps before you debug DECforms escape routines. First, you must tell DECforms that you want to debug escape routines by defining the logical name FORMS$DEBUG_ESCAPE_ROUTINES to be true. This definition tells DECforms to activate the OpenVMS Debugger when it activates the escape routine image for the first time. Because DECforms invokes the OpenVMS Debugger only one time for each image, you must set breakpoints in your escape routines in order to debug them. See the DECforms documentation for more details on the FORMS$DEBUG_ESCAPE_ROUTINES logical name.

By default, both the task I/O stream and the debugger I/O are attached to the same terminal. This is necessary if you have only one terminal to use. However, if two terminals are available to you, you might want to use a separate terminal for each I/O stream. This is useful when you want to see the task output without having debugger prompts overwrite it.

OpenVMS defines the logical names SYS$INPUT and SYS$OUTPUT to be the name of your terminal when you log in (TTA1, for example). The logical names DBG$INPUT and DBG$OUTPUT default to SYS$INPUT and SYS$OUTPUT. If you do not reassign DBG$INPUT and DBG$OUTPUT, both I/O streams are attached to your terminal.

$ DEFINE DBG$INPUT TTA6:
$ DEFINE DBG$OUTPUT TTA6:

In this example, the debug streams are assigned to terminal TTA6.

After setting up your I/O streams for two terminals, follow the instructions in the next section. The breakpoints you set, the commands you use, and the problems to look for are the same as when you debug from a single terminal. The only difference is that the terminal I/O and the debugger I/O display at different terminals. Before starting the debugger, make sure that no one is logged in at the other terminal. If anyone is logged in at the second terminal, the debugger cannot allocate and use that terminal.

$ ACMS/DEBUG VR_TASK_GROUP/WORKSPACE

In the command, include the name of the task group database file (.TDB) containing the task or tasks you want to debug; in the example, the task group is VR_TASK_GROUP. You cannot debug more than one task group at a time. If the file is not in your default device and directory, include the device and directory specifications. The default file type is .TDB.

Use the /WORKSPACE qualifier with the ACMS/DEBUG command to examine and deposit data in workspaces using the Task Debugger. If you do not include the /WORKSPACE qualifier, you can still look at workspaces when a task is running in a server. However, you must use /WORKSPACE if you want to look at workspaces during exchange steps, during the action part of processing steps, or at the beginning or end of the task.

Once the Task Debugger starts, it displays the ACMSDBG> prompt. You can then enter any of the Task Debugger commands. Reference information on all the ACMS Task Debugger commands is in Chapter 10, "ACMS Task Debugger Commands".

ACMS defines process logical names for a server based on logical names that you define using the Task Debugger ASSIGN command. A logical name that you assign in the Task Debugger takes effect only when the server starts. Therefore, if you assign a logical name after a server starts, that name does not take effect.

ACMSDBG> ASSIGN /SERVER=VR_UPDATE_SERVER [AVERTZ.UNAME] AVERTZ_DEFAULT
ACMSDBG> START VR_UPDATE_SERVER

Note that, unlike the DEFINE DCL command, the directory name precedes the logical name in the Task Debugger ASSIGN command. The ACMS Task Debugger ASSIGN command is patterned after the ASSIGN DCL command.

The ASSIGN command defines the logical name AVERTZ_DEFAULT to point to the [AVERTZ.UNAME] directory rather than to the [AVERTZ.PUBLIC] directory. The /SERVER qualifier names the server that can use this logical name: VR_UPDATE_SERVER.

ACMSDBG> SET SERVER VR_UPDATE_SERVER
ACMSDBG> ASSIGN [AVERTZ.UNAME] AVERTZ_DEFAULT

The name included in the SET SERVER command or the /SERVER qualifier must be the same name used for the server in the task group definition.

After starting the ACMS Task Debugger, the next step is to start the servers that handle the tasks you want to debug. The following sections explain how to start, stop, and interrupt servers.

ACMSDBG> START VR_SERVER
Terminal is in SERVER VR_SERVER

                   VAX DEBUG Version V5.4-019
%DEBUG-I-INITIAL - language is COBOL, module set to 'VR_SERVER'
DBG>

DBG> GO
Server VR_SERVER has been started
ACMSDBG>

ACMSDBG> STOP VR_SERVER
Terminal is in SERVER VR_SERVER
Server VR_SERVER stopped
ACMSDBG>

ACMSDBG> STOP VR_SERVER
Stopping only one instance of server VR_SERVER
Terminal is in SERVER VR_SERVER
Server VR_SERVER stopped
ACMSDBG>

ACMSDBG> STOP/ALL
Terminal is in SERVER VR_SERVER
Server VR_SERVER stopped
Terminal is in SERVER VR_SERVER
Server VR_SERVER stopped
Terminal is in SERVER DCL_SERVER
Server DCL_SERVER stopped
ACMSDBG> 

ACMSDBG> INTERRUPT VR_SERVER
Task is in SERVER VR_SERVER
DBG> EXIT
Task is in the task debugger
%ACMSDBG-I-SPDIED, Server VR_SERVER stopped unexpectedly
Processing non-recoverable exception from step $STEP_1 in task VR_RESERVE_TASK
Exception code text:
%ACMS-E-TASK_SP_DIED, Cancel results from the server process dying
Exception code value: 16632498 (decimal), %X00FDCAB2 (hex)
Task was canceled.
ACMSDBG>

ACMSDBG> INTERRUPT VR_SERVER/ TASK=VR_RESERVE_CAR_TASK
Terminal is in server VR_SERVER
DBG> SET BREAK VR_FIND_SI_PROCMAINMAIN-SECTION
DBG> GO

ACMSDBG>

%ACMSDBG-E-SRVNOTUP, Server ... is not started

After you start the servers needed by a task for debugging, you are ready to start the task. However, you might want to set breakpoints before selecting the task.

A breakpoint is a selected place where the debugger stops a task. For example, the first time through a task, you might want to stop the task at the beginning of the action part of each exchange step. You can then check that the information that should be in a workspace is actually there.

ACMSDBG> SET BREAK VR_RESERVE_TASK

In this example, a breakpoint is set in the VR_RESERVE_TASK.

After you have used ACMS Task Debugger commands to examine and deposit data in workspaces, set breakpoints, and so on, enter GO to continue processing from that breakpoint in the task. Otherwise, the step or task cannot complete, and you cannot select another task.

ACMSDBG> @RESERVE_CAR_DBG.COM

Setting up a command file of common commands can make a debugging session much easier.

                                        REPLACE TASK sample_task 
                                          .
                                          .
                                          .
   sample_task\$BEGIN ----------->        BLOCK WITH DISTRIBUTED TRANSACTION 
                                          get_number:
  -------------------------                 EXCHANGE  
 | sample_task\$EXCEPTION  |                    .
 | When exception occurs   |                    .
  -------------------------                     .
  -------------------------
 | sample_task\$CANCEL     |                    
 | When cancellation occurs|                    
  -------------------------                     
                                          get_data:
 
   sample_task\get_data\$BEGIN –>          PROCESSING WORK IS
                                               CALL    sample_procedure
                                               .
                                               .
                                               .
   sample_task\get_data\$ACTION —>           ACTION IS
                                                  SELECT FIRST TRUE OF
                                                  .
                                             .
                                                  .
   sample_task\get_data\$END ------>              END SELECT;
 
                                          display_data;
                                             EXCHANGE
                                             .
                                             .
                                             .
                                          END BLOCK;
 
   sample_task\$ACTION -------------->    ACTION IS
                                             REPEAT STEP;
 
   sample_task\$HANDLER ------------->    EXCEPTION HANDLER ACTION
                                             .
                                             .
                                             .
   sample_task\$END ----------------->    END DEFINITION;

ADU> DUMP GROUP VR_TASK_GROUP /OUTPUT=VR_TASK_GROUP.DMP

 Task group file : UDISK:[UNAME]VR_TASK_GROUP.TDB;5 
    Creation time   :  6-MAR-1991 15:08:29.07
    File size       : 107 BLOCKS
  ==============================================================================
  
                CDD node name : AVERTZ_CDD_GROUP:VR_TASK_GROUP
  
  ==============================================================================
    GROUP workspace count  : 0                             Server count    : 4
    TASK workspace count   : 21                            Task count      : 5
    USER workspace count   : 0
   
    Message file list -
        1. "AVERTZ_DEFAULT:VRMSG.EXE"
  
    No request library
  
    Forms list -
        1. Form: VR_FORM                     File: AVERTZ_DEFAULT:VR_FORM.FORM
 
  
  ==============================================================================
                                    WORKSPACES
  ==============================================================================
    GROUP workspace list -
    USER workspace list -
    TASK workspace list -
        VR_CONTROL_WKSP                                             0
        VR_TRANS_WKSP                                               1
        . 
        .
        .
        ACMS$PROCESSING_STATUS                                      18
        ACMS$TASK_INFORMATION                                       19
        ACMS$SELECTION_STRING                                       20
 
  
  ------------------------------------------------------------------------------
    Workspace name  : VR_CONTROL_WKSP                   Workspace index : 0
    Workspace size  : 127 BYTES                         Workspace type  : TASK
    Owner node name : AVERTZ_CDD_GROUP:VR_TASK_GROUP    Owner type      : GROUP
    Initial content -
        00000000 00000000 00000000 00000000         "................"
          The above line is repeated 6 times (96 BYTES).
        00000000 00000000 00000000 00000000         "..............."
    . 
    .
    .
 
  
  ==============================================================================
                                     SERVERS
  ==============================================================================
  ------------------------------------------------------------------------------
  Group server name  : VR_UPDATE_SERVER              Server index : 1
    Server username    : USERNAME OF APPLICATION      Server type  : PROCEDURE
    Rundown on cancel  : YES, IF INTERRUPTED          Reusable     : YES
    Username attribute : NOT EXPLICITLY SPECIFIED
    Server image file  : "AVERTZ_DEFAULT:VR_UPDATE_SERVER.EXE"
    Execute termination procedure: ALL RUNDOWNS
  .
  .
  .
 
  
  ==============================================================================
                                      TASKS
  . 
  .
  .
  ------------------------------------------------------------------------------
                Task name : VR_COMPLETE_CHECKOUT_TASK
  ------------------------------------------------------------------------------
    Task type            : GLOBAL
    Composable           : YES
    Wait/delay specified : NONE                         Task index    : 4
  
    The following is a list of 5 workspaces that are arguments to this task -
       1.  Workspace name : VR_SENDCTRL_WKSP            Access mode:  READ
       2.  Workspace name : VR_CONTROL_WKSP             Access mode:  MODIFY
       3.  Workspace name : VR_RESERVATIONS_WKSP        Access mode:  MODIFY
       4.  Workspace name : VR_TRANS_WKSP               Access mode:  READ
       5.  Workspace name : VR_VEHICLES_WKSP            Access mode:  READ
 
  
  
    The following is a list of 9 workspaces referenced by this task -
    
       1.  Workspace name : ACMS$PROCESSING_STATUS      Workspace index : 18
           Access type    : UPDATE NO LOCK
           .
           . 
           .
    000 ---------------------------------------------------------------------------
    000     Step name: $TASK             Step type: BLOCK
    000 ---------------------------------------------------------------------------
    000 BLOCK STEP CHARACTERISTICS -
    000     Server context   : RETAINED
    000     I/O method       : REQUEST
    000     Recovery unit    : NOT ACTIVE
    000     Transaction state: STARTING
 
  
  
    000 BLOCK WORK -
    001     -----------------------------------------------------------------------
  001         Step name : PERFORM
    001     -----------------------------------------------------------------------
    001     STEP CHARACTERISTICS -
    
    001         Step type        : PROCESSING     Step index    : 0
            . 
            .
            .
    001     STEP WORK -
  
    001     1.  Conditional      : YES
            . 
            .
            .            
    001         Processing server: VR_UPDATE_SERVER             Server index : 1
    001             The procedure vector index in the server image is 3
    001         2 workspaces passed to the server -
    001             Wksp. name: VR_RESERVATIONS_WKSP            Wksp. index: 5  
    001             Wksp. size: 140
    001             Wksp. name: VR_VEHICLES_WKSP                Wksp. index: 7  
    001             Wksp. size: 71
  
  001     STEP ACTION -
  
    001     1.  Conditional      : YES
    001         Comparison type  : EQUAL
    001         Data type        : TEXT STRING
    001         Source field information -
    001             Source type  : WORKSPACE FIELD
    001             Wksp. name   : ACMS$PROCESSING_STATUS
                . 
                .
                .
    001         Recovery action  : NO RECOVERY ACTION
    001         Transaction action: NO TRANSACTION ACTION
    001         Context action   : RETAIN SERVER CONTEXT IF ACTIVE
    001         Sequencing action: RAISE EXCEPTION
    001             Returning    : A MESSAGE NUMBER
    001             Message no.  : 08018122
                .
                .
                .
    001             Error message will be put into the following workspace :
    001                 Wksp. name   : VR_CONTROL_WKSP
    001                 Wksp. index  : 0
    001                 Field offset : 11
    001                 Field size   : 80
    001         Move Action      : NONE SPECIFIED
     .
     .
     .

$ ACMS/DEBUG VR_TASK_GROUP/WORKSPACE

ADU> START VR_UPDATE_SERVER

ADU> SELECT VR_COMPLETE_CHECKOUT_TASK

ACMSDBG> SET BREAK VR_COMPLETE_CHECKOUT_TASK  PERFORM  $BEGIN

ACMSDBG> SET BREAK VR_COMPLETE_CHECKOUT_TASK  PERFORM  $ACTION

ACMSDBG> SET BREAK called_task$END
ACMSDBG> GO

ACMSDBG> CANCEL BREAK VR_RESERVE_CAR_TASK$BEGIN

ACMSDBG> CANCEL BREAK /ALL=VR_RESERVE_CAR_TASK

ACMSDBG> SELECT VR_RESERVE_CAR_TASK

REPLACE GROUP VR_TASK_GROUP
 .
 .
 .
  TASKS ARE
    RESERVE_CAR  :   TASK IS VR_RESERVE_CAR_TASK;

ACMSDBG> SELECT DISPLAY_EMPLOYEE JONES

In this example, the Display Employee task expects an employee name to be passed to it in the ACMS$SELECTION_STRING workspace. If you enter a name after the task name, ACMS moves the name into the ACMS$SELECTION_STRING workspace and passes it to the task. For further explanation of the use of selection strings, see VSI ACMS for OpenVMS Writing Applications.

ACMSDBG> CANCEL TASK

The CANCEL TASK command does not take any parameters or qualifiers. It always stops the current task, if there is one. If the task has context in a server when it is canceled, and if there is a cancel procedure defined for the server, the cancel procedure runs. If there is a cancel action defined for the task, that action is performed after the server cancel procedure, if any, runs.

When you select a task, the ACMS Task Debugger starts the task. Once the task reaches the first breakpoint, you can enter commands to continue running the task, display the contents of workspaces, change the contents of workspaces, or display information about ACMS Task Debugger commands.

You can use both the ACMS Task Debugger and the OpenVMS Debugger to check values in workspaces.

The following sections explain how to check the workspace values listed above.

ACMSDBG> EXAMINE CHECKOUT_SITE_ID OF VR_VEHICLE_RENTAL_HISTORY_WKSP
CHECKOUT_SITE_ID of VR_CHECKIN_TASK\VR_VEHICLE_RENTAL_HISTORY_WKSP:   0

ACMSDBG> EXAMINE VR_VEHICLE_RENTAL_HISTORY_WKSP
VR_CHECKIN_TASK\VR_VEHICLE_RENTAL_HISTORY_WKSP
VEHICLE_ID: +0
CHECKOUT_SITE_ID:   +0
RESERVATION_ID:     +0
          .
          .
          .

ACMSDBG> EXAMINE CHECKOUT_SITE_ID OF VR_VEHICLE_RENTAL_HISTORY_WKSP
CHECKOUT_SITE_ID of VR_CHECKIN_TASK\VR_VEHICLE_RENTAL_HISTORY_WKSP:   1

ACMSDBG> EXAMINE VR_VEHICLE_RENTAL_HISTORY_WKSP
VR_CHECKIN_TASK\VR_VEHICLE_RENTAL_HISTORY_WKSP
VEHICLE_ID: +2
CHECKOUT_SITE_ID:   +1
RESERVATION_ID:     +26
          .
          .
          .

ACMSDBG> EXAMINE ACMS$T_SEVERITY_LEVEL
ACMS$T_SEVERITY_LEVEL OF VR_RESERVE_CAR_TASK:  S

In an ACMS application definition, you can specify a time limit within which a distributed transaction must complete. If the transaction does not end within the specified number of seconds, ACMS rolls back the transaction.

By default, there is no transaction time limit. Chapter 10, "ACMS Task Debugger Commands" contains reference information about these commands.

ACMSDBG> EXIT
$

If you exit the Task Debugger while server processes are still active, these servers are stopped. If the server has a termination procedure defined for it, the termination procedure is executed.

If there is some reason that you do not want the server's termination procedure to run, you can set a breakpoint at the termination procedure. When you reach the breakpoint, use the EXIT command at the OpenVMS Debugger prompt to cause the server process to exit without executing the termination procedure.

$ DEFINE/SYSTEM/EXEC ACMS$DEBUG_SERVER_SMITH YES

This example uses the /SYSTEM qualifier to define the logical name as a system logical so that the user named SMITH can debug any server on the system.

Define the ACMS$DEBUG_SERVER_vmsusername logical at DCL level as shown in the previous example, using the /SYSTEM, /GROUP, or /TABLE qualifier. A user can debug any server on the system if ACMS$DEBUG_SERVER_vmsusername is defined as an executive mode system logical.

By using the /GROUP qualifier, you can restrict users to debugging only servers in a particular group. You can also define the logical in a server logical name table and point to it from the ACMS application definition. Use the /TABLE qualifier on the DEFINE ACMS$DEBUG_SERVER_vmsusername command if you define the logical in a server logical name table.

You do not need to define the ACMS$DEBUG_SERVER_vmsusername logical if the user has the CMKRNL privilege. ACMS allows any user with the CMKRNL privilege to debug any server.

Although you can authorize several users to debug a server or servers, only one user can debug a server at a time.

To debug a running server, you must link the server to include traceback information. This is required for the OpenVMS Debugger to interrupt the server. By default, the OpenVMS Linker links images with traceback. If the server was linked without traceback (that is, the /NOTRACEBACK qualifier was used on the LINK command), you must relink the server before you can debug it. Then you must replace the server in the running application before continuing.

If a task has context in a server that you are replacing at the time the REPLACE command is issued, the server does not run down until context is released.

You must have OPER privilege to issue the ACMS/REPLACE SERVER command. VSI ACMS for OpenVMS Managing Applications contains more information on replacing servers in a live application.

If you have problems with a particular server, set up the server to provide server process dumps. Then run the task and try to reproduce the situation that causes the server to stop, so that ACMS generates a dump file for analyzing the problem.

First, enable or disable server process dumps in the application definition by using the SERVER PROCESS DUMP clause. You can enable server process dumps in the running application by using the ACMS/MODIFY APPLICATION operator command in an active application. This command temporarily modifies the application definition parameters for the current active application. If you stop and restart the application, the application parameters are reset to their original values.

VSI ACMS for OpenVMS Managing Applications describes the ACMS/MODIFY APPLICATION command and its qualifiers.

Another method of enabling server process dumps is to stop the application, replace the application definition with one that includes the SERVER PROCESS DUMP clause, rebuild the application, and then restart the application. This method permanently enables server process dumps for the server in the application definition.

   .
   .
   .
   SERVER ATTRIBUTES ARE
     UPDATE_SERVER:
       SERVER PROCESS DUMP;
   END SERVER ATTRIBUTES;
   .
   .
   .

When the server terminates abnormally, ACMS writes the context for the server to a dump file located in the default directory for the server. The dump file has the same name as the server. At the same time that ACMS generates the dump file, it also writes a record to the ACMS audit trail log.

If, for some reason, ACMS is unable to generate a server process dump, ACMS writes an audit record to explain the failure. For example, there may be insufficient privileges for ACMS to write the dump file to the server's default directory.

See VSI ACMS for OpenVMS ADU Reference Manual for more information about including the server process dump qualifier in an application definition.

$ ANALYZE/PROCESS_DUMP/IMAGE=avertz_default:vr_update_server_.exe -
_$ vr_update_server.dmp

$ ANALYZE/PROCESS_DUMP/IMAGE=vr_update_server_.exe -
_$ vr_update_server.dmp

Be sure the dump file allows read (R) access before invoking the analyzer. For a complete description of the debugger, see VSI OpenVMS Debugger Manual. VSI OpenVMS DCL Dictionary discusses using the ANALYZE/PROCESS_DUMP DCL command.