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