# Compaq ACMS for OpenVMS
Writing Server Procedures

Previous | Contents | Index

# Part 2
Reference Material

This part of the manual contains reference materials on writing procedures and debugging ACMS tasks and procedures: ACMS programming services and ACMS Task Debugger commands.

# Chapter 9
ACMS Programming Services

This chapter contains reference material for the programming services supplied by ACMS. Table 9-1 summarizes these services. The sections following the table list the services and provide detailed information about how to use each service.

ACMS queuing services are discussed in Compaq ACMS for OpenVMS Writing Applications.

Table 9-1 Summary of the ACMS Programming Services
Service | Description
--- | ---
ACMS$GET_TID | Used by a server procedure to obtain the transaction ID currently associated with an executing task.
ACMS$RAISE_NONREC_EXCEPTION | Raises a nonrecoverable exception. This service is called if a step procedure detects an error from which it cannot recover. ACMS cancels the task when a step procedure raises a nonrecoverable exception.
ACMS$RAISE_STEP_EXCEPTION | Raises a step exception. This service is called if a step procedure detects an error from which it cannot recover, but which the task definition may be able to handle.
ACMS$RAISE_TRANS_EXCEPTION | Raises a transaction exception. This service is called if a step procedure detects an error from which it cannot recover, but which the task definition may be able to handle.

Note The raise-exception programming services differ in an important way from the superseded ACMSAD$REQ_CANCEL service; if a step procedure calls the ACMSAD$REQ_CANCEL service, the service immediately cancels the current task and does not return control to the step procedure. In contrast, after storing the appropriate exception information, the raise-exception services all return control to the step procedure. Once the step procedure completes, the exception is raised in the task.

The format descriptions for the services use OpenVMS procedure parameter notation. Each parameter can have four characteristics, represented by two groups of symbols following the parameter. The characteristics definable for each parameter are:

    <name>.<access type><data type>.<pass mech>

The characteristics are always listed in this order. A period (.) separates access and data types from passing mechanism and parameter form. For example:

    comp_status.wl.r

Table 9-2 defines the symbols used for procedure parameter notation.

Table 9-2 Procedure Parameter Notation
Notation | Symbol | Meaning
--- | --- | ---
Access type | r | Read access only
| w | Write and read access
Data type | l | Longword integer (signed)
| o | Octaword integer (signed)
Passing mechanism | r | By reference

For a complete explanation of all the OpenVMS data structures, data types, access mechanisms and passing mechanisms, see Guide to Creating OpenVMS Modular Procedures.

# ACMS$GET_TID

> Used by a server procedure to obtain the transaction ID (TID) currently associated with an executing task.

## Format

> ACMS$GET_TID (tid.wo.r)

## Parameter

> ### tid

> Address of a 16-byte data structure into which ACMS writes the TID.

## Return Status

> The ACMS$GET_TID service can return the following status values:

> Status | Severity Level | Description
> --- | --- | ---
> ACMS$_NORMAL | Success | Normal successful completion.
> ACMS$_TRANSNOTACT | Error | A distributed transaction is not active at this time.
> ACMS$_INSUFPRM | Error | Insufficient number of arguments supplied to this routine. You must specify a TID argument when you call ACMS$GET_TID.
> ACMS$_INVNUMARGS | Error | Too many arguments supplied to this service. Check the procedure and remove any extraneous arguments.
> ACMS$_NOGETTIDCANPROC | Error | Cannot obtain the transaction ID from a server cancel procedure.
> ACMS$_TASKNOTACTGT | Fatal | ACMS$GET_TID service may not be called when no task is active.

## Note

> This service cannot be called by initialization, termination, or cancel procedures.

## Example

    IDENTIFICATION DIVISION.
       PROGRAM-ID. VR-COMPLETE-CHECKOUT-PROC.
       ...
       DATA DIVISION.
       ...
       WORKING-STORAGE SECTION.
       *
       * Return status to pass to ACMS
       *
       01 RET-STAT         PIC S9(9) COMP.
       .
       .
       .
       *
       * Declare the global transaction context structure.  This is
       * required for SQLPRE
       *
       EXEC SQL INCLUDE
               'AVERTZ_SOURCE:VR_CONTEXT_STRUCTURE_INCLUDE.LIB'
       END-EXEC.
       .
       .
       .
       PROCEDURE DIVISION USING VR_RESERVATIONS_WKSP,
                                VR_VEHICLES_WKSP
                          GIVING RET-STAT.

       MAIN-PROGRAM.
            CALL "ACMS$GET_TID" USING CS-TID GIVING RET-STAT.
           .
           .
           .

> In this example from the AVERTZ sample application, the context structure is defined in the library VR_CONTEXT_STRUCTURE_INCLUDE.LIB. CS-TID is one field in that structure:

    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.

# ACMS$RAISE_NONREC_EXCEPTION

> Raises a nonrecoverable exception if a step procedure detects an error from which it cannot recover. ACMS cancels the current task when a nonrecoverable exception is raised.

## Format

> ACMS$RAISE_NONREC_EXCEPTION ([exception_code.rl.r])

## Parameter

> ### exception_code

> Optional address of a longword containing the exception code.

## Return Status

> The ACMS$RAISE_NONREC_EXCEPTION service can return the following status values:

> Status | Severity Level | Description
> --- | --- | ---
> ACMS$_NORMAL | Success | Normal successful operation; the nonrecoverable exception is raised and the task is canceled as soon as the step procedure completes.
> ACMS$_EXCPTNACTIVE | Error | An exception of the same or higher level has already been raised. The existing exception is raised in the task as soon as the step procedure completes.
> ACMS$_INVNONRECEXCCODE | Error | An invalid nonrecoverable exception code was passed to the service. A nonrecoverable exception is raised, and the task is canceled with the ACMS$_INVNONRECEXCCODE failure status as soon as the step procedure completes.
> ACMS$_NOEXCPTNCANPROC | Error | Cannot raise an exception from a server cancel procedure.
> ACMS$_TSKCANINVARGS | Error | Too many arguments were supplied to this service. A nonrecoverable exception is raised, and the task is canceled with the ACMS$_TSKCANINVARGS failure status as soon as the step procedure completes.
> ACMS$_TASKNOTACTNRE | Fatal | ACMS$RAISE_NONREC_EXCEPTION service may not be called when no task is active.

## Notes

> If an exception code is not supplied, ACMS uses ACMS$_NONRECEXCPTN_PROCSVR; ACMS-E-NONRECEXCPTN_PROCSVR, "Exception resulted from a procedure server calling ACMS$RAISE_NONREC_EXCEPTION." If an exception code is supplied, it must be a failure status.

> If an exception code is supplied that is not a failure status, then ACMS cancels the task with a status of ACMSEXC-E-INVNONRECEXCCODE, "Task canceled: invalid exception code passed to ACMS$RAISE_NONREC_EXCEPTION."

> ACMS sets the appropriate exception information when this service is called; however, the exception is not raised in the task until the step procedure completes. Therefore, a step procedure should return as soon as possible after calling the ACMS$RAISE_NONREC_EXCEPTION service.

> This service cannot be called from a cancel procedure or from an initialization or a termination procedure.

## Example

    IF RET-STAT NOT SUCCESS THEN
           CALL "ACMS$RAISE_NONREC_EXCEPTION" GIVING RSTAT

> In this example, if the return status is not success, then the procedure raises a nonrecoverable exception in the task.

# ACMS$RAISE_STEP_EXCEPTION

> Raises a step exception if a step procedure detects an error from which it cannot recover but which the task definition may be able to handle.

> When a step procedure raises a step exception, the exception falls under the control of the exception handler defined for the processing step or outer-block step, if one exists.

## Format

> ACMS$RAISE_STEP_EXCEPTION ([exception_code.rl.r])

## Parameter

> ### exception_code

> Optional address of a longword containing the exception code.

## Return Status

> The ACMS$RAISE_STEP_EXCEPTION can return the following status values:

> Status | Severity Level | Description
> --- | --- | ---
> ACMS$_NORMAL | Success | Normal successful operation; the step exception is raised in the task as soon as the step procedure completes.
> ACMS$_EXCPTNACTIVE | Error | An exception of the same or higher level has already been raised. The existing exception is raised in the task as soon as the step procedure completes.
> ACMS$_INVSTPEXCCODE | Error | An invalid step exception code was passed to the service. A nonrecoverable exception is raised, and the task is canceled with the ACMS$_INVSTPEXCCODE failure status as soon as the step procedure completes.
> ACMS$_NOEXCPTNCANPROC | Error | Cannot raise an exception from a server cancel procedure.
> ACMS$_TSKCANINVARGS | Error | Too many arguments were supplied to this service. A nonrecoverable exception has been raised, and the task is canceled with the ACMS$_TSKCANINVARGS failure status as soon as the step procedure completes.
> ACMS$_TASKNOTACTSE | Fatal | ACMS$RAISE_STEP_EXCEPTION service may not be called when not task is active.

## Notes

> If an exception code is not supplied, ACMS uses ACMS$_STPEXCPTN_PROCSVR; ACMS-E-STPEXCPTN_PROCSVR, "Exception resulted from a procedure server calling ACMS$RAISE_STEP_EXCEPTION." If an exception code is supplied, it must be a failure status.

> If an exception code is supplied that is not a failure status, then ACMS cancels the task with a status of ACMSEXC-E-INVSTPEXCPTNCODE, "Task canceled: invalid step exception code passed to ACMS$RAISE_STEP_EXCEPTION."

> ACMS stores the appropriate exception information when this service is called; however, the exception is not raised in the task until the step procedure completes. Therefore, a step procedure should return as soon as possible after calling the ACMS$RAISE_STEP_EXCEPTION service.

> This service cannot be called from a cancel procedure or from an initialization or a termination procedure.

## Example

    SQL-ERROR-HANDLER.
            CALL "ACMS$RAISE_STEP_EXCEPTION" USING
                        BY REFERENCE RET-STAT.

> In this example, the SQL error handler raises a step exception that is handled in the task.

# ACMS$RAISE_TRANS_EXCEPTION

> Raises a transaction exception if a step procedure detects an error from which it cannot recover but which the task definition may be able to handle.

> When a step procedure raises a transaction exception, the exception falls under the control of the exception handler defined for the transaction step or outer-block step, if one exists.

## Format

> ACMS$RAISE_TRANS_EXCEPTION ([exception_code.rl.r])

## Parameter

> ### exception_code

> Optional address of a longword containing the exception code.

## Return Status

> The ACMS$RAISE_TRANS_EXCEPTION service can return the following status values:

> Status | Severity Level | Description
> --- | --- | ---
> ACMS$_NORMAL | Success | Normal successful operation; the transaction exception is raised in the task as soon as the step procedure completes.
> ACMS$_INVTRANSEXCCODE | Error | An invalid transaction exception code was passed to the service. A nonrecoverable exception has been raised, and the task is canceled with the ACMS$_INVTRANSEXCCODE failure status as soon as the step procedure completes.
> ACMS$_EXCPTNACTIVE | Error | An exception of the same or higher level has already been raised. The existing exception is raised in the task as soon as the step procedure completes.
> ACMS$_NOEXCPTNCANPROC | Error | Cannot raise an exception from a server cancel procedure.
> ACMS$_TRANSEXCNOTACT | Error | The ACMS$RAISE_TRANS_EXCEPTION service was called by a step procedure, but a transaction was not active. A nonrecoverable exception has been raised, and the task is canceled with the ACMS$_TRANSEXCNOTACT failure status as soon as the step procedure completes.
> ACMS$_TSKCANINVARGS | Error | Too many arguments were supplied to this service. A nonrecoverable exception has been raised, and the task is canceled with the ACMS$_TSKCANINVARGS failure status as soon as the step procedure completes.
> ACMS$_TASKNOTACTTE | Fatal | ACMS$RAISE_TRANS_EXCEPTION service may not be called when no task is active.

## Notes

> If an exception code is not supplied, ACMS uses ACMS$_TRANSEXCPTN_PROCSVR; ACMS-E-TRANSEXCPTN_PROCSVR, "Exception resulted from a procedure server calling ACMS$RAISE_TRANS_EXCEPTION." If an exception code is supplied, it must be a failure status.

> If an exception code is supplied that is not a failure status, then ACMS cancels the task with a status of ACMSEXC-E-INVTRANSEXCCODE, "Task canceled: invalid step exception code passed to ACMS$RAISE_TRANS_EXCEPTION."

> If a step procedure calls the ACMS$RAISE_TRANS_EXCEPTION service when a transaction is not active, then ACMS cancels the task with a status of ACMS$_TRANSEXCNOTACT; ACMS-E-TRANSEXCNOTACT, "Task canceled: ACMS$RAISE_TRANS_EXCEPTION called when no transaction active."

> ACMS sets the appropriate exception information when this service is called; however, the exception is not raised in the task until the step procedure completes. Therefore, a step procedure should return as soon as possible after calling the ACMS$RAISE_TRANS_EXCEPTION service.

> This service cannot be called from a cancel procedure or from an initialization or a termination procedure.

## Example

    SQL-ERROR-HANDLER.

            CALL "ACMS$RAISE_TRANS_EXCEPTION" USING
                        BY REFERENCE RDB$LU_STATUS.

    EXIT PROGRAM.

> The previous example shows how to raise a transaction exception in the error-handling section of a COBOL procedure.

Previous | Next | Contents | Index