| 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.
| #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.
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.
|
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.
| 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. |
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.
| 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. |
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.
| 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 |