| Previous | Contents | Index |
The task clauses and phrases in this chapter are considered to be declining features in the task definition language. It is recommended that you use distributed transaction syntax to control file and database transactions. Most of the clauses and phrases in this chapter are for declaring file and database recovery units in the task definition.
In addition to clauses and phrases related to file and database recovery units, this chapter contains the CONTINUE ON BAD STATUS phrase and the GOTO TASK and REPEAT TASK clauses. It is recommended that you use the RAISE EXCEPTION and EXCEPTION HANDLER clauses instead of CONTINUE ON BAD STATUS; the CALL TASK clause instead of GOTO TASK; and REPEAT STEP instead of REPEAT TASK.
Existing applications that use the clauses and phrases in this chapter can run under ACMS Version 4.0 or higher.
Signals the end of the current transaction in steps you define using DBMS, SQL, Rdb, or RMS recovery units, and causes any changes made since the start of the transaction to be written to the database.
COMMIT [ RETAINING RECOVERY UNIT ] [ IF ACTIVE RECOVERY UNIT ] ;
RETAINING RECOVERY UNIT
Performs the equivalent of a DBMS COMMIT RETAINING. These keywords are valid only with DBMS.IF ACTIVE RECOVERY UNIT
Commits the recovery unit only if there is a recovery unit active. If you use the IF ACTIVE RECOVERY UNIT keywords with the COMMIT clause, and there is no active recovery unit, ACMS does not attempt to COMMIT the recovery unit.If you do not use the IF ACTIVE RECOVERY UNIT keywords, and there is no active recovery unit when you use the COMMIT clause with the RETAINING RECOVERY UNIT keywords, ACMS returns a fatal error.
The COMMIT clause is optional. If you do not use the ROLLBACK, COMMIT, or RETAIN RECOVERY UNIT clause, and the step started a unit, the default recovery action is COMMIT IF ACTIVE RECOVERY UNIT.Table 7-1 shows the default recovery actions for different cases in a task definition.
Use the RETAINING RECOVERY UNIT keywords only if you are using the COMMIT clause in the action specification for a step within a block.Use the COMMIT clause with the CANCEL TASK clause to commit a recovery unit while still canceling the task.
If the server process does not receive a cancel, ACMS does not take any recovery actions specified with the CANCEL TASK clause. Instead, the procedure server image is run down. This rundown causes a rollback of any active recovery units. Therefore, you must be careful when using the CANCEL TASK and COMMIT clauses in the same action specification.
PROCESSING WITH DBMS RECOVERY "READY CONCURRENT UPDATE"
CALL PERSADD USING PERS_RECORD;
CONTROL FIELD ACMS$T_STATUS_TYPE
"B" : GET ERROR MESSAGE;
ROLLBACK;
GOTO PREVIOUS EXCHANGE;
NOMATCH : COMMIT;
END CONTROL FIELD;
|
If the PERSADD procedure returns a status code with an error severity level of WARNING, ERROR, or FATAL, ACMS stores the value B in the ACMS$T_STATUS_TYPE field of the ACMS$PROCESSING_STATUS workspace. When ACMS processes the CONTROL FIELD clause and B is in the ACMS$T_STATUS_TYPE field, ACMS returns to the previous exchange step and restores the database to the state it was in at the start of the recovery unit. However, if any other value is in the ACMS$T_STATUS_TYPE field, denoted by the NOMATCH keyword, ACMS commits all changes made since the start of the recovery unit.
Instructs ACMS to continue task execution if a task called by a processing step returns a failure status.
CONTINUE ON BAD STATUS
The CONTINUE ON BAD STATUS phrase is optional.If you do not use the CONTINUE ON BAD STATUS phrase, the calling task is canceled if the called task returns a bad status.
The CONTINUE ON BAD STATUS phrase is ignored if it is specified in a processing step that also uses a CALL PROCEDURE clause.
REPLACE TASK MENU_TASK
GLOBAL;
NOT CANCELABLE;
WORKSPACE IS WORK_RECORD,PERS_RECORD;
BLOCK WORK
PROCESSING
CALL PROCEDURE DISPLAY IN DISPLAY_SERVER;
EXCHANGE
READ PERS_RECORD;
ACTION IS
MOVE PERS_RECORD INTO WORK_RECORD.ENTRY;
PROCESSING WITH CONTINUE ON BAD STATUS
IS
SELECT FIRST TRUE
( WORK_RECORD.ENTRY EQ "ADD_EMPLOYEE"):
CALL TASK ADD_EMPLOYEE;
( WORK_RECORD.ENTRY EQ "REVIEW_UPDATE"):
CALL TASK REVIEW_UPDATE;
( WORK_RECORD.ENTRY EQ "GET_EMPLOYEE"):
CALL TASK GET_EMPLOYEE;
( WORK_RECORD.ENTRY EQ "EXIT"):
NO PROCESSING;
NOMATCH:
NO PROCESSING;
END SELECT ;
END BLOCK WORK;
ACTION IS
SELECT FIRST TRUE OF
( WORK_RECORD.ENTRY NE "EXIT"):
REPEAT TASK;
( WORK_RECORD.ENTRY EQ "EXIT"):
EXIT TASK;
NOMATCH:
REPEAT TASK;
END SELECT ;
END DEFINITION;
|
In this example, the processing step in the task definition for MENU_TASK includes a CONTINUE ON BAD STATUS phrase. If a task called by the processing step returns a bad status, MENU_TASK continues to execute.
The DBMS RECOVERY phrase readies a DBMS database at the start of a block or processing step. If you use the DBMS RECOVERY phrase to start your transaction, you must end your transaction with a COMMIT or ROLLBACK clause.
DBMS RECOVERY dml-string [,...]
dml-string
The Data Manipulation Language (DML) string is the DML statement with which you ready the DBMS database. The DML string can contain any legal READY statement syntax, including realm name or names and access and allow characteristics. You can specify multiple READY statements by separating them with commas. Refer to the DBMS documentation for further information on the DML READY statement.Specifying realms and their usage characteristics is optional. The two kinds of usage characteristics you can define for a realm are:
- Allow characteristics
- Access characteristics
An allow characteristic describes how other users can use the realm or realms you are readying. Use one of four keywords to define this characteristic: CONCURRENT, PROTECTED, EXCLUSIVE, or BATCH.
An access characteristic describes how the task can use the realm or realms you are readying. Use the keyword UPDATE or RETRIEVAL to define this characteristic.
The default usage characteristics are PROTECTED RETRIEVAL. Use BATCH RETRIEVAL to start a snapshot transaction.
READY is the only DML statement allowed in a DML string. If you omit the realm name, ACMS readies all realms in the subschema used by the server in which the processing step is running. You can include multiple DML strings to ready different realms with different usage characteristics.
ADU supports DML strings up to a length of 255 characters.
When you enter strings longer than 255 characters into ADU, ACMS issues a warning, and the string is truncated. To overcome this restriction, put DBMS RECOVERY statements in procedure servers rather than in task definitions.
The DBMS RECOVERY phrase is optional. If you do not include it, ACMS does not ready the DBMS database in the block or processing step.
ACMS calls DBQ$INTERPRET to execute each DML statement that you supply with the DBMS RECOVERY phrase to specify database allow and access characteristics. Readying the database for UPDATE access starts a recovery unit. To use the DBMS RECOVERY phrase, you must bind the database in the server initialization procedure.Use the DBMS RECOVERY phrase only when defining a processing step or block step. When you use the DBMS RECOVERY phrase at the start of a processing step or block step, ACMS sets the default recovery action for that step to COMMIT IF ACTIVE RECOVERY. You cannot use the DBMS RECOVERY phrase when defining a nested block.
You cannot use the DBMS RECOVERY phrase in a processing step that runs in a DCL server.
If you use the DBMS RECOVERY phrase and the NO PROCESSING clause in the same processing step, ACMS cancels the task.
You must use separate servers for DBMS, Rdb, RMS, and SQL if you are using recovery units with more than one of these products in the same application. Only one type of recovery unit can be used for each server or step. You cannot specify more than one RECOVERY statement (RDB, DBMS, RMS, or SQL) for the same block or processing step. Table 7-1 shows the default recovery actions for different situations in a task definition.
| Default Recovery Action | ||
|---|---|---|
| Action Clause | If you started the recovery unit in the current step | If you did not start the recovery unit in the current step |
|
ROLLBACK IF ACTIVE RECOVERY UNIT | ROLLBACK IF ACTIVE RECOVERY UNIT |
|
COMMIT IF ACTIVE RECOVERY UNIT | COMMIT IF ACTIVE RECOVERY UNIT |
|
COMMIT IF ACTIVE RECOVERY UNIT | NO RECOVERY UNIT ACTION |
| #1 |
|---|
BLOCK WITH DBMS RECOVERY "READY PERSONNEL CONCURRENT UPDATE"
|
ACMS starts a recovery unit, readying the PERSONNEL realm for concurrent update. You do not use a semicolon after the DML string because DBMS RECOVERY is a phrase rather than a clause.
| #2 |
|---|
BLOCK WITH DBMS RECOVERY "READY PERSONNEL CONCURRENT UPDATE",
"READY CUSTOMER CONCURRENT RETRIEVAL"
|
ACMS starts a recovery unit, readying the PERSONNEL realm for concurrent update. ACMS also readies the CUSTOMER realm for concurrent retrieval. You do not use a semicolon after the DML string because DBMS RECOVERY is a phrase rather than a clause.
| #3 |
|---|
REPLACE TASK REVIEW_SCHEDULE_TASK
DEFAULT SERVER IS DEPARTMENT_SERVER;
WORKSPACES ARE REVIEW_SCHEDULE_WKSP, QUIT_WORKSPACE;
BLOCK
WORK WITH FORM I/O
SERVER CONTEXT
DBMS RECOVERY "READY DEPART ADMIN CONCURRENT RETRIEVAL"
GET_DEPT_NUMBER:
EXCHANGE
RECEIVE FORM RECORD REVIEW_SCHEDULE_INPUT_RECORD
RECEIVING REVIEW_SCHEDULE_WKSP
WITH RECEIVE CONTROL QUIT_WORKSPACE;
CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
" FEXT" : EXIT TASK;
END CONTROL FIELD;
GET_FIVE_EMPLOYEES:
PROCESSING
CALL REVIEW_SCHEDULE_GET
USING REVIEW_SCHEDULE_WKSP;
CONTROL FIELD ACMS$T_STATUS_TYPE
"B" : GET ERROR MESSAGE;
GOTO PREVIOUS EXCHANGE;
END CONTROL FIELD;
DISPLAY_EMPLOYEES:
EXCHANGE
SEND FORM RECORD REVIEW_SCHEDULE_OUTPUT_RECORD
SENDING REVIEW_SCHEDULE_WKSP
WITH RECEIVE CONTROL QUIT_WORKSPACE;
CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
" FMOR" : GOTO PREVIOUS PROCESSING;
" FEXT" : EXIT TASK;
END CONTROL FIELD;
END BLOCK WORK;
ACTION
REPEAT TASK;
END DEFINITION;
|
In the REVIEW_SCHEDULE_TASK, a user can look at the review schedule information for a department. The user looks at five records at a time and can then indicate whether or not to see more records. To keep track of the user's location in the file, you must retain currency indicators. A recovery unit is not created for this transaction because it is a RETRIEVAL transaction. Server context is maintained for the task to preserve database currency indicators across retrievals.
| #1 |
|---|
PROCESSING WITH DBMS RECOVERY "READY PERSONNEL"
|
ACMS readies the PERSONNEL realm. The default ready access and allow characteristics are PROTECTED RETRIEVAL.
| #2 |
|---|
PROCESSING WITH DBMS RECOVERY "READY PERSONNEL CONCURRENT RETRIEVAL",
"READY CUSTOMER CONCURRENT UPDATE"
|
ACMS readies the PERSONNEL realm for concurrent retrieval and the CUSTOMER realm for concurrent update.
| #3 |
|---|
PROCESSING WITH DBMS RECOVERY "READY CONCURRENT UPDATE"
CALL REVIEW_UPDATE_GET IN DEPARTMENT_SERVER
USING PERS_RECORD,HIST_RECORD,PERS_RECORD;
CONTROL FIELD ACMS$T_STATUS_TYPE
"B" : GET ERROR MESSAGE;
ROLLBACK;
GOTO PREVIOUS EXCHANGE;
END CONTROL FIELD;
|
ACMS starts a recovery unit for the processing step, readying all the realms in the subschema for concurrent update. In this step, if the procedure named REVIEW_UPDATE_GET procedure is unsuccessful, ACMS returns the value "B" to the ACMS$T_STATUS_TYPE of the ACMS$PROCESSING_STATUS system workspace. ACMS then retrieves an error message and performs a ROLLBACK, returning the database to the state it was in at the beginning of the processing step.
Ends the current task and starts a new task without requiring the terminal user to make a task selection.
task-name
The name of a task in the same task group. This name is the name assigned to the task in the TASKS clause of the task group definition.workspace-name
The name of the workspace or workspaces you want to pass from the current task to the new task. The workspace names in the current task must match those in the new task. They do not, however, need to be in the same order in the WORKSPACES clause of the new task.
The GOTO TASK clause is optional. The default sequencing action for a step within a block is GOTO NEXT STEP. The default sequencing action for a block step or a processing step in a single-step task is EXIT TASK.When you chain from one task to another with the GOTO TASK clause, ACMS always passes the ACMS system workspaces.
When one task chains to another, ACMS does not check the access control list for the second task before starting the second task.
If there are workspaces that you do not pass from one task to another but that appear in the definition of the task being chained to, ACMS initializes those workspaces with the initial contents defined for their record descriptions in the dictionary.
Because a distributed transaction must end in the action part of the step on which it starts, you cannot specify GOTO TASK in the action part of a step within a distributed transaction. If you specify GOTO TASK in the action part of a root block, that task cannot be called by a parent task to participate in a distributed transaction.When you use the GOTO TASK clause in a step that does not start a distributed transaction, the default recovery action is COMMIT IF ACTIVE RECOVERY UNIT, and the default context action is RELEASE SERVER CONTEXT IF ACTIVE SERVER CONTEXT.
If you use the GOTO TASK clause, you cannot declare the following clauses in the same action specification:
- RETAIN RECOVERY UNIT
- RETAIN RECOVERY UNIT IF ACTIVE RECOVERY UNIT
- RETAIN SERVER CONTEXT
- RETAIN SERVER CONTEXT IF ACTIVE SERVER CONTEXT
If the task passes workspaces with the GOTO TASK clause, the task being chained to must declare all the workspaces named in the GOTO TASK clause in a WORKSPACE or USE clause. Also, the task you are chaining to must use all the workspaces passed in a GOTO TASK clause in an exchange or processing step.
ACTION
GOTO TASK DISPLAY_BASIC PASSING DISPLAY_WORKSPACE;
|
This example unconditionally ends the current task and starts a new task named DISPLAY_BASIC. The workspace DISPLAY_BASIC is passed to the new task.
Specifies that there is no action taken on any active recovery unit.
NO RECOVERY UNIT ACTION ;
The NO RECOVERY UNIT ACTION clause is optional. Table 7-2 shows the default recovery actions for different cases of a task definition.
If there is an active recovery unit and you use the NO RECOVERY UNIT ACTION clause, ACMS retains the recovery unit. If there is no active recovery unit and you use the NO RECOVERY UNIT ACTION clause, ACMS takes no recovery actions.If you use the NO RECOVERY UNIT ACTION clause and release server context, either explicitly or by default, while there is an active recovery unit, ACMS cancels the task.
BLOCK WITH
FORM I/O
SERVER CONTEXT
DBMS RECOVERY "READY CONCURRENT UPDATE"
GET_DEPT_NUMBER:
EXCHANGE
RECEIVE FORM RECORD REVIEW_SCHEDULE
RECEIVING REVIEW_SCHEDULE_WKSP
WITH RECEIVE CONTROL QUIT_WORKSPACE;
CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
" FCAN" : CANCEL TASK;
END CONTROL FIELD;
GET_FIVE_EMPLOYEES:
PROCESSING
CALL REVIEW_SCHEDULE_GET IN DEPARTMENT_SERVER
USING REVIEW_SCHEDULE_WKSP;
CONTROL FIELD ACMS$T_STATUS_TYPE
"B" : GET ERROR MESSAGE;
GOTO PREVIOUS EXCHANGE;
"G" : NO RECOVERY ACTION;
NO CONTEXT ACTION;
GOTO NEXT STEP;
END CONTROL FIELD;
|
If the REVIEW_SCHEDULE_GET procedure is successful in retrieving review schedule information for a department, ACMS returns the value "G" to the ACMS$T_STATUS_TYPE field of the ACMS$PROCESSING_STATUS system workspace. In this task, the user can choose to look at the next record in the file. Therefore, you want to retain currency indicators to maintain the user's file location. Because the recovery unit was started at the block level, there is already an active recovery unit for the processing step. Use the NO RECOVERY UNIT ACTION clause to maintain that recovery unit.
Starts an Rdb database transaction at the beginning of a block or processing step. If you use the RDB RECOVERY phrase to start your transaction, you must end your transaction with a COMMIT or ROLLBACK clause.
RDB RECOVERY dml-string [,...]
dml-string
The Data Manipulation Language (DML) string is a DML statement with which you start an Rdb database transaction at the block or processing step level. The DML string can contain any legal START_TRANSACTION syntax, including the characteristics you want to apply to the transaction. Use the DML RESERVING clause to apply different characteristics to different relations.ADU supports DML strings up to a length of 255 characters.
When you enter strings longer than 255 characters into ADU, ACMS issues a warning, and the string is truncated. To overcome this restriction, put RDB RECOVERY statements in procedure servers rather than in task definitions.
For more information on DML strings, refer to the Rdb documentation.
The RDB RECOVERY phrase is optional. If you do not include it or the SQL RECOVERY phrase, ACMS does not start an RDB database transaction.
ACMS calls RDB$INTERPRET to execute the DML statement that you supply to start the database transaction. Starting an update transaction creates a recovery unit. To use the RDB RECOVERY phrase, you must bind the database in the server initialization procedure.Use the RDB RECOVERY phrase only when defining a processing step or block step. When you use the RDB RECOVERY phrase at the start of a processing step or block step, ACMS sets the default recovery action for that step to COMMIT IF ACTIVE RECOVERY.
You cannot use the RDB RECOVERY phrase in a processing step that runs in a DCL server.
You cannot use the RDB RECOVERY phrase with a nested block.
If you use the RDB RECOVERY phrase and the NO PROCESSING clause in the same processing step, ACMS cancels the task.
You must use separate servers for DBMS, Rdb, RMS, and SQL procedures if you are using recovery units with more than one of these products in the same application. Only one type of recovery unit can be used per server or step. You cannot specify more than one recovery statement (RDB, DBMS, RMS, or SQL) for the same block or processing step. Table 7-2 shows the default recovery actions for different situations in a task definition.
Table 7-2 Default Recovery Actions Default Recovery Action Action Clause If you started the recovery unit in the current step If you did not start the recovery unit in the current step
- CANCEL TASK
- RAISE EXCEPTION
ROLLBACK IF ACTIVE RECOVERY UNIT ROLLBACK IF ACTIVE RECOVERY UNIT
- EXIT TASK,
- GOTO TASK,
- REPEAT TASK,
- RELEASE CONTEXT,
- RELEASE CONTEXT
- IF ACTIVE
- RECOVERY UNIT
COMMIT IF ACTIVE RECOVERY UNIT COMMIT IF ACTIVE RECOVERY UNIT
- OTHER
COMMIT IF ACTIVE RECOVERY UNIT NO RECOVERY UNIT ACTION
| #1 |
|---|
BLOCK WITH RDB RECOVERY
"START_TRANSACTION READ_WRITE RESERVING EMPLOYEES FOR SHARED WRITE"
|
ACMS starts an Rdb transaction that can store, modify, and erase data in the EMPLOYEES relation. SHARED specifies that other users can work with the EMPLOYEES relation while you are working with it, and WRITE specifies that you can store, modify, or erase data in the relation. You do not use a semicolon (;) after the database string because RDB RECOVERY is a phrase rather than a clause.
| #2 |
|---|
BLOCK WITH RDB RECOVERY
"START_TRANSACTION READ_WRITE RESERVING " &
"EMPLOYEES FOR SHARED READ, " &
"SALARY_HISTORY FOR SHARED WRITE, " &
"JOBS FOR EXCLUSIVE WRITE"
|
Previous Next Contents Index