# Compaq ACMS for OpenVMS
Writing Server Procedures

Previous | Contents | Index

# Part 5
Appendixes

This part of the manual contains supplemental information that may be useful when writing server procedures for Compaq ACMS for OpenVMS applications.

Appendix A contains a summary of ACMS system workspaces. Appendix B lists the libraries included in the AVERTZ sample procedures. Appendix C describes superseded features of Compaq ACMS for OpenVMS.

# Appendix A
Summary of ACMS System Workspaces

The three ACMS system workspaces are:

- ACMS$PROCESSING_STATUS
- ACMS$SELECTION_STRING
- ACMS$TASK_INFORMATION

Each ACMS system workspace has a different purpose. All of the Common Data Definition Language (CDDL) record definitions for these workspaces are stored in the CDD$TOP.ACMS$DIR.ACMS$WORKSPACES directory in the CDD. This appendix lists these workspaces and explains the uses of each.

# A.1 ACMS$PROCESSING_STATUS System Workspace

The ACMS$PROCESSING_STATUS workspace handles processing status information. It has four fields, each for a different part of that information. The CDD location of the CDDL record definition for this workspace is CDD$TOP.ACMS$DIR.ACMS$WORKSPACES.ACMS$PROCESSING_STATUS.

Table A-1 describes the fields in the ACMS$PROCESSING_STATUS workspace.

Table A-1 Fields in the ACMS$PROCESSING_STATUS Workspace
ACMS$L_STATUS
Type: | Signed longword
Description: | Contains the return status from the last processing step. The initial value of the ACMS$L_STATUS field is set to 1 (SUCCESS) when a task is started.
ACMS$T_SEVERITY_LEVEL
Type: | Text
Size: | 1 character
Description: | Contains a single-character severity level code representing the return status in the ACMS$L_STATUS field. The characters this field can contain are: S (SUCCESS), I (INFORMATION), W (WARNING), E (ERROR), F (FATAL), or ? (OTHER). The initial value of ACMS$T_SEVERITY_LEVEL is S.
ACMS$T_STATUS_TYPE
Type: | Text
Size: | 1 character
Description: | Contains a single-character severity level code representing the return status in the ACMS$L_STATUS field. G indicates the low bit in the ACMS$L_STATUS field is set to 1. B indicates the low bit is clear. The initial value of the ACMS$T_STATUS_TYPE field is G.
ACMS$T_STATUS_MESSAGE/ACMS$T_STATUS_MESSAGE_LONG
Type: | Text
Size: | 80/132 characters
Description: | ACMS$T_STATUS_MESSAGE is an 80-character variant of the 132 character ACMS$T_STATUS_MESSAGE_LONG field. When you use the GET ERROR MESSAGE clause, this field contains the error message associated with the return status code in ACMS$L_STATUS. The ACMS$T_STATUS_MESSAGE_LONG field is set initially to spaces.

# A.2 ACMS$SELECTION_STRING System Workspace

The ACMS$SELECTION_STRING workspace handles strings passed by a task submitter (terminal user) at task selection time. This workspace has a single field. The CDD location of the CDDL record definition for this workspace is CDD$TOP.ACMS$DIR.ACMS$WORKSPACES.ACMS$SELECTION_STRING.

Table A-2 describes the field in the ACMS$SELECTION_STRING workspace.

Table A-2 Field in the ACMS$SELECTION_STRING Workspace
ACMS$T_SELECTION_STRING
Type: | Text
Size: | 255 characters
Description: | Contains the selection string provided by a terminal user at task selection time. If the user does not provide a selection string, ACMS sets the field to spaces. If the task is queued, the first 32 bytes of the selection string contain the queued task element ID.

# A.3 ACMS$TASK_INFORMATION System Workspace

The ACMS$TASK_INFORMATION workspace handles task execution information. It has ten fields, each for a different part of that information. The CDD location of the CDDL record definition for this workspace is CDD$TOP.ACMS$DIR.ACMS$WORKSPACES.ACMS$TASK_INFORMATION.

Table A-3 describes the fields in the ACMS$TASK_INFORMATION workspace.

Table A-3 Fields in the ACMS$TASK_INFORMATION Workspace
ACMS$AL_TASK_ID
Type: | Signed longword array
Size: | 4 longwords
Description: | Contains the task ID in binary format for the current task instance; the ACMS$AL_TASK_ID field is a four-element longword array. It is possible for two task instances to have the same value if the tasks are selected on two different nodes. To ensure a unique task identifier, use both the ACMS$AL_TASK_ID field and the ACMS$T_SUBMITTER_NODE field.
ACMS$L_TASK_SEQUENCE_NUMBER
Type: | Signed longword
Description: | Contains the number of the current task instance within the current task. This field always contains 1 when the task is initially selected from a menu. ACMS increments this number each time the user repeats the task or chains to another task, thus starting a new task instance without returning to the menu.
ACMS$T_TASK_NAME
Type: | Text
Size: | 31 characters
Description: | Contains the task name as defined in the application under which the task is running. ACMS does not update this field when one task chains to another.
ACMS$T_TASK_IO_DEVICE
Type: | Text
Size: | 8 characters
Description: | Contains the device name for the task submitter. For remote users, the device name is always NL:. For local request I/O or terminal I/O users, this field includes the terminal device name. For stream I/O or no I/O, this field is set to spaces. If this field contains a device name (not spaces or NL:), then the device can be used by the task to perform I/O from a processing step.
ACMS$AL_TASK_SUBMITTER_ID
Type: | Signed longword array
Size: | 4 longwords
Description: | Contains the current terminal user's identification code for the user who started the current task instance. This field is a four-element longword array.
ACMS$T_TASK_USERNAME
Type: | Text
Size: | 12 characters
Description: | Contains the OpenVMS user name for the terminal user who started the current task instance. For remote tasks, this is the name of the proxy.
ACMS$T_SUBMITTER_NODE_NAME
Type: | Text
Size: | 15 characters
Description: | Contains the DECnet node name for the task submitter.
ACMS$L_CALL_SEQUENCE_NUMBER
Type: | Signed longword
Description: | Contains the call sequence number of the currently called task. ACMS increments this number each time a task calls another task.
ACMS$T_SIGN_IN_USERNAME
Type: | Text
Size: | 12 characters
Description: | Contains the OpenVMS user name of the user on the submitter node. If a submitter selects a remote task, then the user name under which that task runs may be different from the user name under which the submitter signed in. The contents of the ACMS$T_TASK_USERNAME are based on the proxy lookup and user name defaulting mechanism and may differ from the ACMS$T_SIGN_IN_USERNAME field. If a submitter selects a local task, the ACMS$T_SIGN_IN_USERNAME field is the same as the ACMS$T_TASK_USERNAME field. To distinguish between users that have the same name but reside on different nodes, use the ACMS$T_SIGN_IN_USERNAME field with the ACMS$T_SUBMITTER_NODE_NAME field to log the user name and the node location.
ACMS$T_SIGN_IN_DEVICE
Type: | Text
Size: | 8 characters
Description: | Contains the name of the device that was supplied to ACMS when the submitter signed in. For applications using the ACMS command process, this field contains a terminal device name. For applications using a user-written command process (agent), this field can contain a terminal device name, the name of a nonterminal device that the agent is handling, or the NL: device specification. Use the ACMS$T_SIGN_IN_DEVICE field in conjunction with the ACMS$T_SUBMITTER_NODE_NAME field to log the device name and its node location. Use both fields to distinguish between devices that have the same name but reside on different nodes.

# Appendix B
Libraries Included in AVERTZ Sample Procedures

This appendix lists the contents of the libraries referred to in procedures that are part of the AVERTZ sample application.

# B.1 VR_MESSAGES_INCLUDE.LIB

    *
    * AVERTZ messages
    *
    *
    * Informational
    *
    01 MULCURECFND          PIC S9(9) COMP VALUE IS EXTERNAL VR_MULCURECFND.
    01 MULRSRECFND          PIC S9(9) COMP VALUE IS EXTERNAL VR_MULRSRECFND.
    01 VEUPGPRF             PIC S9(9) COMP VALUE IS EXTERNAL VR_VEUPGPRF.
    01 VEDNGPRF             PIC S9(9) COMP VALUE IS EXTERNAL VR_VEDNGPRF.
    01 CURECUPD             PIC S9(9) COMP VALUE IS EXTERNAL VR_CURECUPD.
    01 CURECINS             PIC S9(9) COMP VALUE IS EXTERNAL VR_CURECINS.
    01 CHKINCOMP            PIC S9(9) COMP VALUE IS EXTERNAL VR_CHKINCOMP.
    01 CHKOUTCOM            PIC S9(9) COMP VALUE IS EXTERNAL VR_CHKOUTCOM.
    01 RESVCOMP             PIC S9(9) COMP VALUE IS EXTERNAL VR_RESVCOMP.
    01 VERECFND             PIC S9(9) COMP VALUE IS EXTERNAL VR_VERECFND.
    01 RESSUCCNCLD          PIC S9(9) COMP VALUE IS EXTERNAL VR_RESSUCCNCLD.
    *
    * Warning
    *
    01 CURECNOTFND          PIC S9(9) COMP VALUE IS EXTERNAL VR_CURECNOTFND.
    01 RCRECNOTFND          PIC S9(9) COMP VALUE IS EXTERNAL VR_RCRECNOTFND.
    01 RERECNOTFND          PIC S9(9) COMP VALUE IS EXTERNAL VR_RERECNOTFND.
    01 RSRECNOTFND          PIC S9(9) COMP VALUE IS EXTERNAL VR_RSRECNOTFND.
    01 SIRECNOTFND          PIC S9(9) COMP VALUE IS EXTERNAL VR_SIRECNOTFND.
    01 VERECNOTFND          PIC S9(9) COMP VALUE IS EXTERNAL VR_VERECNOTFND.
    01 VRHRECNOTFND         PIC S9(9) COMP VALUE IS EXTERNAL VR_VRHRECNOTFND.
    01 NOTCHKOUT            PIC S9(9) COMP VALUE IS EXTERNAL VR_NOTCHKOUT.
    01 RESCNCLD             PIC S9(9) COMP VALUE IS EXTERNAL VR_RESCNCLD.
    01 CARCHKIN             PIC S9(9) COMP VALUE IS EXTERNAL VR_CARCHKIN.
    01 CARCHKOUT            PIC S9(9) COMP VALUE IS EXTERNAL VR_CARCHKOUT.
    01 RESCLOSED            PIC S9(9) COMP VALUE IS EXTERNAL VR_RESCLOSED.
    01 DLRENOTFND           PIC S9(9) COMP VALUE IS EXTERNAL VR_DLRENOTFND.
    01 NOCANCEL             PIC S9(9) COMP VALUE IS EXTERNAL VR_NOCANCEL.
    01 INACTIVE             PIC S9(9) COMP VALUE IS EXTERNAL VR_INACTIVE.
    01 DDTM_TIMEOUT         PIC S9(9) COMP VALUE IS EXTERNAL VR_DDTM_TIMEOUT.
    *
    * Error
    *
    01 NO_DUP               PIC S9(9) COMP VALUE IS EXTERNAL VR_NO_DUP.
    01 DEADLOCK             PIC S9(9) COMP VALUE IS EXTERNAL VR_DEADLOCK.
    01 INTEG_FAIL           PIC S9(9) COMP VALUE IS EXTERNAL VR_INTEG_FAIL.
    01 LOCK_CONFLICT        PIC S9(9) COMP VALUE IS EXTERNAL VR_LOCK_CONFLICT.
    01 CAR_UNAVAILABLE      PIC S9(9) COMP VALUE IS EXTERNAL VR_CAR_UNAVAILABLE.
    01 CHK_CANCL_ERR        PIC S9(9) COMP VALUE IS EXTERNAL VR_CHK_CANCL_ERR.
    01 HIST_WRITE_ERR       PIC S9(9) COMP VALUE IS EXTERNAL VR_HIST_WRITE_ERR.
    01 UPDATE_ERROR         PIC S9(9) COMP VALUE IS EXTERNAL VR_UPDATE_ERROR.
    *
    * Fatal
    *
    01 BILLERR              PIC S9(9) COMP VALUE IS EXTERNAL VR_BILLERR.
    01 DB_FATAL             PIC S9(9) COMP VALUE IS EXTERNAL VR_DB_FATAL.
    01 ICRECNOTFND          PIC S9(9) COMP VALUE IS EXTERNAL VR_RCRECNOTFND.

# B.2 VR_LITERALS_INCLUDE.LIB

    01 C-ZERO       PIC X VALUE "0".
    01 C-NINE       PIC X VALUE "9".
    01 C-ONE        PIC X VALUE "1".
    01 NEG-ONE      PIC S9(4) COMP VALUE -1.

# B.3 VR_SQL_STATUS_INCLUDE.LIB

    *
    * Define the SQL return status
    *
    01 SQL_NOTFOUND         PIC S9(9) COMP VALUE +100.
    01 SQL_NO_DUP           PIC S9(9) COMP VALUE -803.
    01 SQL_DLOCK            PIC S9(9) COMP VALUE -913.
    01 SQL_INTEGFAIL        PIC S9(9) COMP VALUE -1001.
    01 SQL_LOCK             PIC S9(9) COMP VALUE -1003.
    01 SQL_SELMORVAL        PIC S9(9) COMP VALUE -811.
    *

# B.4 VR_CONTEXT_STRUCTURE_INCLUDE.LIB

    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.

# Appendix C
Superseded Features

This appendix describes features used in earlier versions of ACMS. Although you can continue to use these features, they have been superseded by new features and are considered to be declining functionality.

# ACMSAD$REQ_CANCEL

> Cancels a task. ACMS writes the task cancellation to the audit trail log. When you include a reason parameter, the call also writes the reason for the cancellation to the audit trail log.

> Note This programming service is a declining feature. Beginning with ACMS Version 3.2, use ACMS$RAISE_NONREC_EXCEPTION to raise an exception that cancels a task.

## Format

> ACMSAD$REQ_CANCEL ([reason.rl.r])

## Parameter

> ### reason

> Optional longword address of the reason for canceling, passed by reference as a read-only longword value.

## Return Status

> The ACMSAD$REQ_CANCEL service can return the following status values:

> Status | Severity Level | Description
> --- | --- | ---
> ACMS$_NORMAL | Success | Normal successful completion.
> ACMS$_PENDING | Informational | Successful operation pending asynchronous completion.
> 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$_INVREQCANREASON | Error | Task canceled: invalid cancel reasons passed to ACMS$_INVREQCANREASON.
> ACMS$_NOCANCELCANPROC | Error | ACMSAD$REQ_CANCEL service may not be called from a server cancel procedure.
> ACMS$_TASKNOTACTRC | Fatal | ACMSAD$REQ_CANCEL service may not be called when no task is active.

## Notes

> The optional parameter reason must be a condition value. For example, the parameter can be a symbol in a message file you have created, or it can be an OpenVMS or RMS condition value.

> If a reason (that is, an exception code) is not supplied, ACMS uses ACMS$_CANCEL_PROCSVR, "Cancel resulting from procedure server calling ACMSAD$REQ_CANCEL." If a reason is supplied, it must be a failure status. If a reason is supplied that is not a failure status, then ACMS cancels the task with a status of ACMS$_INVCANCELREASON, "invalid cancel reason."

> The behavior of ACMSAD$REQ_CANCEL depends on whether or not AST delivery is enabled. If the ACMSAD$REQ_CANCEL service is called with AST delivery enabled, then the nonrecoverable exception is raised immediately, and the service does not return to the procedure. If the ACMSAD$REQ_CANCEL service is called with AST delivery disabled, then the service returns ACMS$_PENDING, and the nonrecoverable exception is raised when AST delivery is once again enabled. Note that the step procedure must enable AST delivery before completing.

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

##

### Examples

#1
    WORKING-STORAGE SECTION.
    01 CNCL_MSG      PIC S9(5)
                        VALUE IS EXTERNAL "MSG_CANCEL".

    PROCEDURE DIVISION.
    .
    .
    .
    CALL "ACMSAD$REQ_CANCEL" USING CNCL_MSG.

> In this COBOL example, MSG_CANCEL is a message symbol in an external message file. CNCL_MSG is a data item declared with MSG_CANCEL as its value.

#2
    CALL ACMSAD$REQ_CANCEL

> This BASIC example shows how to cancel the task with the default reason of ACMS$_ACMSTP_CALL, ACMSI-E-ACMSTP_CALL, "Cancel resulting from procedure server calling ACMSAD$REQ_CANCEL."

Index | Contents