|
HP OpenVMS Systems Documentation |
|
Compaq ACMS for OpenVMS
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Previous | Contents | Index |
Identifies the block or processing step as a transaction; all work within the step must complete successfully or be rolled back.
DISTRIBUTED TRANSACTION
The TRANSACTION phrase is optional. If you do not include it, ACMS does not process the step as a transaction.
You can start a distributed transaction on a root block, nested block, root processing step, or a processing step that is part of a multiple-step task. A distributed transaction must end in the action part of the step that started the transaction. Use the COMMIT TRANSACTION clause to make permanent the file or database operations performed within the distributed transaction. Use the ROLLBACK TRANSACTION clause to return files and databases to the state they were in before the start of the distributed transaction.If you do not specify COMMIT TRANSACTION or ROLLBACK TRANSACTION in the action part of a step that starts a distributed transaction, ACMS commits the distributed transaction. However, if the action part of the step specifies CANCEL TASK or RAISE EXCEPTION, ACMS rolls back the distributed transaction.
If a distributed transaction fails to complete successfully, ACMS cancels the task. Depending upon the reason for the failure, you might want the task to continue to execute instead of canceling. See EXCEPTION HANDLER Clause (Block, Exchange, Processing) and Compaq ACMS for OpenVMS Writing Applications for information on using the EXCEPTION HANDLER ACTION clause to recover from transaction failures.
You can include a called task within a distributed transaction started by the parent task. For a called task to be able to participate in a distributed transaction, it must conform to the following rules:
- The root block or root processing step must specify the TRANSACTION phrase.
- The action part of the root block or root processing step cannot specify any sequencing action clauses other than EXIT TASK, CANCEL TASK, or RAISE EXCEPTION.
- The action part of the root block or root processing step cannot specify COMMIT TRANSACTION or ROLLBACK TRANSACTION.
- The root block or root processing step cannot contain an EXCEPTION HANDLER ACTION component.
- The root block or root processing step cannot specify the CANCEL ACTION phrase.
A task that conforms to the above rules is a composable task.
Because a distributed transaction must end in the action part of the step on which it started, you cannot specify EXIT TASK, GOTO TASK, or REPEAT TASK on a step within a distributed transaction.
You cannot conditionalize a processing step that starts a distributed transaction by using the WHILE DO clause. Instead, you can either include a loop in the processing step's procedure, or specify WHILE DO on a block step that includes the processing step.
You cannot declare an RMS file or a database recovery unit within a distributed transaction by specifying RMS RECOVERY, DBMS RECOVERY, RDB RECOVERY, or SQL RECOVERY in the task definition. You can, however, declare a recovery unit in the procedure.
ACMS automatically retains server context between steps within a distributed transaction. Therefore, you cannot specify the RELEASE SERVER CONTEXT action clause within a distributed transaction. When a transaction ends, ACMS automatically releases server context. You cannot specify the RETAIN SERVER CONTEXT or NO SERVER CONTEXT ACTION clause in the action part of the step that started a distributed transaction.
Within a distributed transaction, you can exclude a processing step from participating in the transaction by specifying the NONPARTICIPATING SERVER phrase. See NONPARTICIPATING SERVER Phrase (Processing) for information on how to use this phrase.
You can choose to start and end a distributed transaction in a procedure, rather than in the task definition, by using the $START_TRANS, $END_TRANS, and $ABORT_TRANS system services.
Table 3-19 shows the default transaction actions for different situations in a task definition.
| Action Clause | Default Transaction Action | |
|---|---|---|
| If you started the distributed transaction in the current step | If you did not start the distributed transaction in the current step | |
|
ROLLBACK TRANSACTION | no transaction action |
| OTHER | COMMIT TRANSACTION | no transaction action |
BLOCK WORK WITH FORMS I/O
EXCHANGE
RECEIVE FORM RECORD ORDER_ENTRY_RECORD IN ORDER_ENTRY_FORM
RECEIVING ORDER_ENTRY_RECORD;
BLOCK WORK WITH DISTRIBUTED TRANSACTION
PROCESSING
SELECT FIRST TRUE OF
( ( PRIORITY_ORDER = "Y" ) AND
( ORDERED_AMOUNT > IN_STOCK_AMOUNT ) ):
CALL PRIORITY_ORDER IN MASTER_DATABASE_SERVER
USING ORDER_ENTRY_RECORD, RESTOCK_RECORD,
STATUS_RECORD;
( ORDERED_AMOUNT > IN_STOCK_AMOUNT ):
CALL QUEUE_REPLENISH_INVENTORY_TASK IN QUEUE_SERVER
USING RESTOCK_RECORD;
END SELECT;
END BLOCK WORK;
ACTION IS
IF ( ORDER_SATISFIED = "Y" )
THEN COMMIT TRANSACTION;
EXIT TASK;
ELSE ROLLBACK TRANSACTION;
END IF;
END BLOCK WORK;
|
In this example, the Order Entry task starts a distributed transaction on the nested block. The processing step calls a procedure to write an order record to the distribution center's database. If the distribution center cannot immediately satisfy the order, the processing step inserts a queued task into a queue file. However, if it is a priority order, the processing step checks the master database to see if the manufacturing plant can satisfy the order. If the order is handled successfully, the action part of the nested block commits the transaction. Otherwise, it ends the transaction by rolling back any database updates performed within the transaction.
Combines the SEND and RECEIVE operations. First, DECforms sends information from your task workspace to form data items. Then, it moves data from the form to your task workspace.
send-record-identifier
The name of the form record that defines how data is sent from your task workspace to form data items. The record identifier can also name a form record list.receive-record-identifier
The name of the form record that defines how your task workspace receives data from form data items. The record identifier can also name a form record list.form-label-name
The name of the form that contains the records named by the record identifiers. This is the name assigned to the form by using the WITH NAME keywords in the FORMS clause of the task group definition.send-workspace-name
The given name of the workspace that contains the information you want to transfer to the form.send-shadow-workspace
The given name of the workspace that can contain an indicator that instructs the DECforms whether or not to update last-known values of form data items.receive-workspace-name
The given name of the task workspace that receives data from the form.receive-shadow-workspace
The given name of the workspace that contains indicators about which fields in the receive workspace have changed as a result of the exchange with the form. The first field in the workspace must be a one-character field into which DECforms can store a value indicating whether or not the receive workspace has changed.receive-control-workspace
The given name of the workspace that contains status information about the completed TRANSCEIVE operation. DECforms returns status information in the form of receive control text items. Each receive control text item is five characters long.numeric-workspace-field2
The name of a workspace field that contains the number of receive control text items in the receive control workspace. This number indicates the number of receive control text items returned by DECforms. Each item is five bytes in length. The data type of the workspace field must be signed or unsigned longword. The value of the field is set after the DECforms request is completed.send-control-workspace
The given name of the workspace that contains up to five send control text items to be passed to DECforms. For each send control text item, you must define a corresponding control text response within the form.numeric-workspace-field3
The name of a workspace field that contains the number of send control text items in the send control workspace. You specify the number of control text items in the send control workspace. The data type of the workspace field must be signed or unsigned longword. The value of the field must be set before the DECforms request is executed.send-control-count
The number of send control text items in the send control workspace. You specify the number of control text items in the send control workspace.numeric-workspace-field
The given name of the workspace field that identifies the maximum time allowed between operator entries. To specify a time limit, you can either create a workspace field that contains the number of seconds, or you can hardcode the number of seconds in the exchange step clause.The workspace field is in the workspace that you name in the task definition with the WORKSPACES clause. If you name more than one workspace with the WORKSPACES clause, you must name the workspace and the field in the TIMEOUT argument.
seconds
The maximum number of seconds that can elapse between operator entries. To specify a time limit, you can either create a workspace field that contains the number of seconds, or you can hardcode the number of seconds in the exchange step clause.
The TRANSCEIVE clause is optional.
If you do not specify the form in the TRANSCEIVE clause, and you do not name a default form in the task definition, ACMS uses the first form named in the task group definition.If the operator does not make an entry within the TIMEOUT limit, ACMS cancels the task. If you omit the TIMEOUT argument or if you specify zero seconds, the operator has unlimited time between entries.
To use the control text COUNT clauses at run time, both the submitter node and application node must have ACMS Version 3.3 or higher installed. If the application node has ACMS Version 3.3 or higher, and the submitter node has a previous version of ACMS, then ACMS cannot pass the control text count values between the application node and the submitter node. In this case, a step exception is raised in the task with the TPS$_NOCNTRLCNTSUB error status.
If the application node has a version of ACMS lower than Version 3.3, then the control text COUNT clause is ignored at run time, and cannot be updated.
| #1 |
|---|
TRANSCEIVE FORM RECORD EMPLOYEE_INFO_RECORD, EMPLOYEE_INFO_RECORD
IN EMPLOYEE_INFO_LABEL
SENDING EMPLOYEE_INFO_WKSP SHADOW IS SEND_EMPLOYEE_INFO_SHADOW
RECEIVING EMPLOYEE_INFO_WKSP SHADOW IS REC_EMPLOYEE_INFO_SHADOW
WITH TIMEOUT 30;
|
The SEND part of this step uses the form record EMPLOYEE_INFO_RECORD to move data from the task workspace EMPLOYEE_INFO_WKSP to the form data items stored in the form EMPLOYEE_INFO_LABEL. SEND_EMPLOYEE_INFO_SHADOW is the send-shadow-workspace that instructs DECforms whether or not to update last-known values of form data items.
The RECEIVE part of this step uses the form record EMPLOYEE_INFO_RECORD to move data from form data items stored in the form EMPLOYEE_INFO_LABEL to the task workspace EMPLOYEE_INFO_WKSP. REC_EMPLOYEE_INFO_SHADOW is the receive-shadow-workspace that identifies which fields in EMPLOYEE_INFO_WKSP have changed because of the exchange with the form.
The TIMEOUT argument establishes 30 seconds as the maximum time that can elapse between operator entries.
You can use a TRANSCEIVE clause that sends and receives the same form record and task workspace to let the operator display and then update form data items.
| #2 |
|---|
EXCHANGE
TRANSCEIVE RECORD MY_RECORD, MY_RECORD
SENDING MY_RECORD
RECEIVING MY_RECORD
WITH SEND CONTROL SEND_CNTRL COUNT CNTRL_COUNTS.SEND_COUNT
RECEIVE CONTROL RECV_CNTRL COUNT CNTRL_COUNTS.RECV_COUNT;
|
When this request completes, DECforms returns the control text items into the RECV_CNTRL workspace, and returns the number of control items into the CNTRL_COUNTS.RECV_COUNT field. For instance, if DECforms returns two control text items, which are " F001" and " F002", the contents of the workspace RECV_CNTRL become " F001 F002", and the field CNTRL_COUNTS.RECV_COUNT equals 2.
Names one or more workspaces, declared in the task group, to which a task needs access.
workspace-name
The given name or assigned name of the workspace declared in the WORKSPACES clause of the task group definition. It is not a CDD path name. Use commas to separate workspaces you declare. Any workspaces you declare must be named in a WORKSPACES clause of the task group definition.
ACCESS
Identifies the access characteristics of a workspace. The types of access you can define are RETRIEVAL and UPDATE. You can only define access characteristics for GROUP and USER type workspaces. The default access type is specified in the WORKSPACES clause in the task group definition. If you do not specify an access type in the WORKSPACES clause, the default access type is RETRIEVAL.LOCK
Indicates that a task instance can lock the workspace from use by other tasks when the task starts and can unlock it when the task stops or is canceled. If you do not use the LOCK keyword, the workspace is not locked. The keyword applies only to GROUP and USER workspaces defined to have UPDATE access.RETRIEVAL
Indicates that a task can use and make changes to the contents of the workspace. However, when the task finishes, ACMS does not copy changes into the master copy of the workspace. RETRIEVAL is the default access for GROUP and USER workspaces.UPDATE
Indicates that the task can make changes to the contents of the workspace. When the task finishes, ACMS copies these changes to the master copy of the workspace. Unless you use the LOCK keyword, ACMS does not lock the workspace against updates by other tasks or users.
The USE WORKSPACES clause is optional. If you do not use the USE WORKSPACES clause, workspaces declared in the task group are not available to the task.
You can use the USE WORKSPACES clause multiple times in a single task definition.ADU lets you use the LOCK keyword when defining a TASK workspace. However, this keyword has no effect at run time.
You cannot declare a workspace type for workspaces you name in a USE WORKSPACES clause.
Do not name the ACMS system workspaces in the USE WORKSPACES clause. ACMS system workspaces are available to each task by default.
If you declare a workspace with ACCESS UPDATE (either LOCK or NOLOCK), any other task can use the workspace with ACCESS RETRIEVAL. However, if you declare a workspace with ACCESS UPDATE (either LOCK or NOLOCK), ACMS cancels, at the beginning of the task instance, any other task or instance of the same task that attempts to use the same workspace with ACCESS UPDATE (either LOCK or NOLOCK).
The sum of the sizes of all workspaces referenced in a task definition must not exceed 65,535 bytes.
| #1 |
|---|
USE WORKSPACE DEPT_WORKSPACE WITH RETRIEVAL;
|
In this example, the name of the workspace in the task group definition is DEPT_WORKSPACE. The task can only read and use the contents of this workspace. It cannot make changes to the contents.
| #2 |
|---|
USE WORKSPACE DEPT_WORKSPACE WITH UPDATE LOCK;
|
In this example, the task has update access to the DEPT_WORKSPACE workspace and locks the workspace from access by other tasks.
Controls whether or not ACMS displays a message prompting users to press [Return]. Pressing [Return] clears the terminal screen and displays the previous ACMS menu.
[ NO ] WAIT ;
The ACMS-supplied default is NO WAIT. This clause is optional.
If you use the WAIT clause in a task definition, you must include it before the processing or block step for that definition.You cannot use the WAIT clause and the DELAY clause in the same definition.
The WAIT and DELAY clauses determine how quickly ACMS returns user control to a menu when a task ends. If a user runs a task that displays the time of day, for example, with the SHOW TIME command, by default ACMS displays the time, but then immediately clears the screen and returns to the menu. Both clauses let you delay the time between the end of a task and the return to the selection menu.
If you do not specify a WAIT clause or set the wait attribute in an application definition TASK ATTRIBUTES clause, ACMS uses the setting you assign in the task group definition. If you do not make an assignment there, ACMS uses the NO WAIT default.
WAIT and DELAY clauses in a menu definition override attributes specified in a task, task group, or application definition.
WAIT;
|
ACMS waits for the user to press [Return] before clearing the final screen of the task and returning the user to a menu.
Performs work as long as a specified Boolean expression evaluates to true.You can use a WHILE DO clause to start a block, exchange, or processing step (thereby creating a conditional block, exchange, or processing step). The WHILE DO clause uses a Boolean expression to compare workspace fields and takes actions based on the result of the expression. As long as the expression evaluates to true, ACMS performs the action associated with the DO keyword. When the expression evaluates to false, control falls through to the next step.
- WHILE (boolean-expression)
- DO <clause>
- END WHILE;
boolean-expression
The Boolean expression must be an expression that ACMS can evaluate as either true or false. As long as the Boolean expression is true, ACMS does the work defined by the corresponding clause. When the expression evaluates to false, control falls through to the next step. You must enclose Boolean expressions in parentheses.See Section 3.10 for a description of Boolean expressions.
clause
One of the following, depending on where you place the WHILE DO clause:
block
The start of a nested block with the keywords BLOCK WORK or the start of an exchange or processing step with the keywords EXCHANGE WORK or PROCESSING WORK, respectively. When you use the WHILE DO clause at the block step level, you can specify multiple block, exchange, and processing steps to correspond with the Boolean expression.
At the block step level, you can use the WHILE DO clause only at the top of the block; you cannot use it between steps within the block.
exchange-clause
Any unconditional exchange clause that is compatible with the I/O method the block step uses. For example, if a block step uses FORM I/O, exchange steps in that block step can use one of the DECforms clauses (SEND, RECEIVE, or TRANSCEIVE) or NO EXCHANGE, but cannot use a TDMS clause (READ, WRITE, or REQUEST). There can be only one exchange clause for the Boolean expression that you specify.
processing-clause
Any unconditional processing clause. There can be only one processing clause for the Boolean expression that you specify.
Table 3-20 summarizes the clauses you can use within the WHILE DO clause at each step.
| At This Step | You Can Specify | ||
|---|---|---|---|
| BLOCK | Multiple of: | ||
|
|||
| PROCESSING | One of: | ||
|
|||
| EXCHANGE | If task uses FORM I/O | If task uses REQUEST I/O | If task uses STREAM I/O |
| One of: | One of: | One of: | |
|
|
|
DO
Identifies the work to perform as long as the Boolean expression evaluates to true.
The WHILE DO clause is optional. If you do not use the WHILE DO clause or one of the other three conditional clauses, ACMS processes your block, exchange, or processing work unconditionally.
You must end each subclause in a WHILE DO clause with a semicolon (;), and you must end the WHILE DO clause with END WHILE and a semicolon (;).The type of clause you can use within a WHILE DO clause depends on the type of step that you are defining. For example, if you are using WHILE DO to define an exchange step, you can only use exchange clauses.
If you use WHILE DO at the block step level, you can only use it at the top of the block; you cannot specify it between steps within the block.
You cannot conditionalize a processing step that starts a distributed transaction by using the WHILE DO clause. Instead, you can either include a loop in the processing step's procedure, or specify WHILE DO on a block step that includes the processing step.
| #1 |
|---|
BLOCK WORK
WHILE (OLD_WORKSPACE NE NEW_WORKSPACE)
DO
EXCHANGE
SEND FORM RECORD EMPLOYEE_INFO_RECORD
SENDING EMPLOYEE_INFO_WKSP;
PROCESSING
CALL EMPLOYEE_UPDATE IN PERSONNEL
USING PERS_RECORD, UPDATE_WORKSPACE;
ACTION IS
MOVE 1 INTO NUMBER_WORKSPACE;
END WHILE;
END BLOCK;
|
ACMS tests the contents of OLD_WORKSPACE and NEW_WORKSPACE. As long as the Boolean expression evaluates to true, ACMS performs the exchange and processing steps associated with the DO keyword. If the expression evaluates to false, control falls through to the next step.
| #1 |
|---|
EXCHANGE
WHILE (EMP_CNTRL_WKSP.STATUS_FIELD EQ "INVAL")
DO
TRANSCEIVE RECORD EMPLOYEE_INFO_RECORD, EMPLOYEE_INFO_RECORD
SENDING EMPLOYEE_INFO_WKSP
RECEIVING EMPLOYEE_INFO_WKSP
END WHILE;
ACTION IS EXIT TASK;
|
Previous Next Contents Index