Compaq ACMS for OpenVMS
ADU Reference Manual


Previous Contents Index

In this example definition, the user retrieves and modifies information about an employee. The SQL transaction is specified on the block step. If the operation fails (either in retrieving or updating the information), the transaction is rolled back; otherwise, the updates are committed. Note that server context and the recovery unit are retained after the first processing step.


Processing Phrase Examples

#1

PROCESSING WITH 
  SQL RECOVERY "SET TRANSACTION READ WRITE RESERVING " & 
    "DEPART FOR SHARED READ, ADMIN FOR PROTECTED WRITE" 
      

This DML string starts a read-write transaction, allowing read-only access to the DEPART table and protected write access to the ADMIN table. No other tables are available for access.

#2

PROCESSING WITH SQL RECOVERY 
  "SET TRANSACTION READ WRITE RESERVING EMPLOYEES FOR SHARED WRITE" 
      

ACMS starts a recovery unit for a transaction that can store, modify, and erase data in the EMPLOYEES table. SHARED specifies that other users can work with the EMPLOYEES table while you are working with it, and WRITE specifies that you can store, modify, or erase data in the table. Do not use a semicolon (;) after the database string because SQL RECOVERY is a phrase rather than a clause.

#3

GET_EMPLOYEE_ID_TASK 
  DEFAULT SERVER IS EMPLOYEE_SERVER; 
  BLOCK WORK WITH FORM I/O 
    EXCHANGE 
       RECEIVE FORM RECORD GET_EMPLOYEE_ID_RECORD 
         RECEIVING EMPLOYEE_ID_WKSP 
         WITH RECEIVE CONTROL QUIT_WORKSPACE; 
       CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY 
         " FEXT"   :  EXIT TASK; 
       END CONTROL FIELD; 
 
    PROCESSING WITH SQL RECOVERY 
      "SET TRANSACTION READ WRITE RESERVING EMPLOYEES FOR SHARED WRITE" 
       CALL GET_EMPLOYEE_INFO 
         USING EMPLOYEE_ID_WKSP; 
       CONTROL FIELD ACMS$T_STATUS_TYPE 
        "G"     :  RETAIN SERVER CONTEXT; 
                   RETAIN RECOVERY UNIT; 
                   GOTO NEXT STEP; 
        "B"     :  ROLLBACK; 
                   GOTO PREVIOUS TASK; 
       END CONTROL FIELD; 
 
    EXCHANGE 
       SEND FORM RECORD GET_EMPLOYEE_ID_RECORD 
         SENDING EMPLOYEE_ID_WKSP 
         WITH RECEIVE CONTROL QUIT_WORKSPACE; 
       CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY 
         " FEXT"   :  ROLLBACK; 
                      CANCEL TASK; 
       END CONTROL FIELD;            
 
    PROCESSING 
       CALL WRITE_EMPLOYEE_INFO 
         USING EMPLOYEE_ID_WKSP; 
       CONTROL FIELD ACMS$T_STATUS_TYPE 
        "G"     :  COMMIT; 
        "B"     :  ROLLBACK; 
                   CANCEL TASK; 
       END CONTROL FIELD; 
  END BLOCK; 
END DEFINITION; 
      

In this example, the user retrieves and modifies information about an employee. The SQL transaction is specified on the first processing step. If the information about the employee cannot be retrieved, the transaction is rolled back and the initial exchange is repeated. If the update fails, the transaction is rolled back and the task canceled. Note that server context and the recovery unit are retained after the first processing step.


Appendix A
ADU Error Messages

Error message documentation for ADU is contained in a file named SYS$SYSROOT:[SYSHLP]ACMSADU.MEM. You can also access error message documentation from within ADU by typing:


ADU> HELP ERRORS

You will find an explanation of the error message and suggested user action. For example:


ERRORS Subtopic? APPLUSENAME
ERRORS 
 
  APPLUSENAME 
 
     Application user name is missing - must be defined 
 
     Explanation:  You tried to create or replace an application 
     definition that does not include the APPLICATION USERNAME 
     clause. 
 
     User Action:  Include the APPLICATION USERNAME clause in the 
     application definition.  Then use the CREATE or REPLACE command 
     to store the definition in the CDD.


Appendix B
Summary of ACMS System Workspaces

The three ACMS system workspaces each have 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.

B.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 B-1 describes the fields in the ACMS$PROCESSING_STATUS workspace.

Table B-1 Fields in ACMS$PROCESSING_STATUS
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 indicating the severity level of the return status in the ACMS$L_STATUS field. A "G" indicates the low bit in the ACMS$L_STATUS field is set to 1. A "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.

B.2 ACMS$SELECTION_STRING System Workspace

The ACMS$SELECTION_STRING workspace handles strings passed by a task submitter (terminal user) at task selection time. It 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 B-2 describes the field in the ACMS$SELECTION_STRING workspace.

Table B-2 Fields in ACMS$SELECTION_STRING
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 a queued task, the first 32 bytes of the selection string contain the queued task element ID.

B.3 ACMS$TASK_INFORMATION System Workspace

The ACMS$TASK_INFORMATION workspace handles task execution information. It has 10 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 B-3 describes the fields in the ACMS$TASK_INFORMATION workspace.

Table B-3 Fields in ACMS$TASK_INFORMATION
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 that two task instances can have the same value, if the tasks have been 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; the content of this field is always one (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 a task chains to another task.
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 they signed in. The contents of the ACMS$T_TASK_USERNAME is 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 with the ACMS$T_SUBMITTER_NODE_NAME field to log the device name and its node location. It is necessary to use both of these fields if you wish to distinguish between devices that have the same name but are residing on different nodes.


Index Contents