| Previous | Contents | Index |
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.
The three ACMS system workspaces are:
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.
| 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.
| 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. |
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.
| 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. |
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. |
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. |
* * 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. * |
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. |
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.
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.
ACMSAD$REQ_CANCEL ([reason.rl.r])
reason
Optional longword address of the reason for canceling, passed by reference as a read-only longword value.
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.
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.
| #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 |