| Previous | Contents | Index |
A called task can use a different I/O method than the task that called it. For example, a menu task using form I/O can call tasks that use terminal I/O or ACMS stream I/O as well as other form I/O tasks. If you want a task that uses form I/O or terminal I/O to call a task that uses stream I/O, a user-written agent must associate a stream ID with a submitter ID. For more information, see Compaq ACMS for OpenVMS Systems Interface Programming.
Although a stream ID can be associated with a submitter ID, it is not possible to associate a terminal device specification with a stream ID. A stream I/O task called by an agent can call only other stream I/O tasks or tasks that do no I/O. A stream I/O task called by an agent cannot call or chain to a task that performs local or remote requests or that performs terminal I/O from a server.
Describes the work done in a block step in terms of block, exchange, processing, and action clauses.A BLOCK clause encloses a multiple-step task.
block-phrase
Attributes of a block step. Section 3.3 explains block phrases.block-conditional-clause
A clause that tests the values of workspace fields to determine what block, exchange, or processing steps to perform. Section 3.4 explains block conditional clauses.label
Name of a step. A label is required only if the step is referred to by another step in the task. Labels are also useful when debugging the task definition. If you do not use a label for a step definition, ACMS supplies a default step label in the form of $STEP_n where n is the sequential number of the step within the block step. You can refer to ACMS-supplied labels only when using the ACMS Task Debugger. You cannot use ACMS-supplied step labels when using the GOTO STEP action clause.To assign a step label, use a 1- to 31-character identifier.
block-step
A nested block. ACMS lets you nest block steps within other block steps. Section 3.2 explains nested blocks.exchange-clause
A clause that describes the work done in an exchange step. Section 3.5 explains exchange step clauses.processing-phrase
Attributes of a processing step. Section 3.6 explains processing step phrases.processing-clause
A clause that describes the work done in a processing step. Section 3.6 explains processing step clauses.action-clause
A clause that describes conditional or unconditional actions you want to take at the end of a block, exchange, or processing step. Section 3.8 explains action clauses. Section 3.9 explains how to use action clauses in the exception handler part of a step.
You must use either the BLOCK clause or the PROCESSING clause to define the work a task does.
REPLACE TASK ADD_EMPLOYEE_TASK
WORKSPACES ARE EMPLOYEE_INFO_WKSP, QUIT_WORKSPACE;
BLOCK
WORK WITH FORM I/O
EXCHANGE
RECEIVE FORM RECORD EMPLOYEE_INFO_RECORD
RECEIVING EMPLOYEE_INFO_WKSP
WITH RECEIVE CONTROL QUIT_WORKSPACE;
CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
" FQUT" : EXIT TASK;
END CONTROL FIELD;
PROCESSING
CALL ADD_EMPL_INFO IN EMPL_SERVER
USING EMPLOYEE_INFO_WKSP
CONTROL FIELD ACMS$T_STATUS_TYPE
"B" : GET ERROR MESSAGE;
GOTO PREVIOUS EXCHANGE;
END CONTROL FIELD;
END BLOCK WORK;
ACTION
REPEAT STEP;
END DEFINITION;
|
In this example, the block phrase FORM I/O is used to indicate that the exchange step in the block uses DECforms to perform I/O. The keywords BLOCK WORK signal the start of the work part of the block step. The work for the block is done by one exchange step and one processing step. The keywords END BLOCK WORK indicate that the work for the block is done. The action taken when the block work is done is REPEAT STEP, which repeats the task.
Names a procedure in a procedure server to do the work for a processing step and any workspaces used by that procedure.
CALL PROCEDURE entry-point-name [IN server-name] [USING workspace-name [,...] ];
entry-point-name
The entry point name of the procedure in the procedure server image. The entry point name cannot be named TASK or PROCEDURE unless the PROCEDURE keyword is specified.server-name
The name of the server in which ACMS runs the procedure named by the CALL clause. When you use the CALL clause, the server you name must be a procedure server. The server you name must be declared in the definition of the task group containing the task you are defining. If you do not name a server, ACMS uses the server named in the DEFAULT SERVER clause in the task part of the task definition.workspace-name
The given name of the workspace or workspaces the procedure uses. Use the given name or unique name of each workspace. If you list more than one workspace name, you must separate the names with commas. All workspace names must be defined in the WORKSPACES or USE WORKSPACES clause of the task definition. The order of the workspace names must be the same as the order of the workspaces specified in the procedure parameter list. ACMS passes workspaces to the procedure by reference.
If you do not use the CALL clause in a processing step, ACMS does not call a procedure to do work for that step.
Any procedure you name with the CALL clause must exist in a procedure server.You can name separate servers in different processing steps or for processing clauses listed for different values of a CONTROL FIELD clause.
WRITE_EMPLOYEE_RECORD:
PROCESSING
CALL PERSADD IN PERSONNEL
USING ADD_WORKSPACE, PERS_RECORD;
|
The WRITE_EMPLOYEE_RECORD step uses the PERSONNEL server to run the PERSADD procedure that uses the workspaces ADD_WORKSPACE and PERS_RECORD.
Names a task to be called by a processing step and any workspaces that can be supplied to the called task.
CALL TASK task-name [ USING workspace-name [ ,... ] ] ;
task-name
The given name of the task to be called by the processing step of a calling task. Both the calling task and the called task must be in the same task group.You cannot specify a task definition CDD path name or application task name.
workspace-name
The given name of the workspace or workspaces passed to the called task. Use the given name or unique name of each workspace. If you list more than one workspace name, you must separate the names with commas. All workspace names must be defined in the TASK ARGUMENT phrase of the task definition of the task being called. The order of the workspace names must be the same as the order of the workspaces specified in the TASK ARGUMENT clause of the called task.ACMS passes workspaces to a called task by position. The contents of the first workspace identified by the USING phrase in the parent task are moved into the first workspace named in the TASK ARGUMENTS clause in the called task, and so on, for each workspace named in the USING phrase.
You do not have to specify a workspace.
If you do not use the CALL TASK clause in a processing step, ACMS does not call another task.
You can specify either a task, user, group, or system workspace as an argument to pass to the called task. However, it is not good practice to pass system workspaces as arguments to called tasks. If individual fields from a system workspace in the calling task are required by a called task, pass them to the called task in a task workspace. Data can be moved from a system workspace into a task workspace using a MOVE clause in the task definition or within a procedure called from a processing step.To pass a system workspace to a called task, define the corresponding TASK ARGUMENT workspace in the called task for READ access. This protects the contents of the system workspace from accidental modification and performs faster than if you define the workspace for MODIFY access.
A called task can participate in a distributed transaction started by a parent task if the called task conforms to the following rules. The root block or root processing step:
- Must include the DISTRIBUTED TRANSACTION phrase
- Cannot include a sequencing action clause other than EXIT TASK, CANCEL TASK, or RAISE EXCEPTION
- Cannot include the COMMIT TRANSACTION or ROLLBACK TRANSACTION action clause
- Cannot include an exception handler
- Cannot include the CANCEL ACTION phrase
A task that conforms to the above rules is a composable task.
After a called task completes, execution of the calling task continues with the action part of the calling processing step. The status fields in the processing status workspace are updated to reflect the status returned by the called task and can be used by the calling task to control subsequent task execution. Subsequent execution of the calling task can be controlled using fields in task workspaces or by using the final completion status and ACMS symbolic message code of the called task.
If the called task is defined with the AUDIT attribute, an audit record is always written to the Audit Trail Logger whenever a task is called or chained from an agent or another task.
ACMS always performs a task access control list check to determine if a task can be executed by the submitter. ACMS does not perform an access control check when a task chains to another task using the GOTO TASK clause.
PROCESSING
CALL TASK ENTER_ORDER USING ORDER_WORKSPACE;
EXCEPTION HANDLER ACTION IS
SELECT FIRST TRUE OF
( ACMS$L_STATUS = ACMS$_CALL_CANCELED ):
GOTO STEP SUBMITTER_CANCEL;
( ACMS$L_STATUS = ACMS$_OPR_CANCELED ):
GOTO STEP OPERATOR_CANCEL;
END SELECT;
|
In this example, the CALL TASK clause specifies that the processing step calls the task ENTER_ORDER using the workspace ORDER_WORKSPACE. If the call is not canceled, ACMS continues execution to the next step in the task. If the ENTER_ORDER task is canceled by [Ctrl/Y], control goes to the SUBMITTER_CANCEL step. If the task is canceled by an operator using the ACMS/CANCEL TASK operator command, control goes to the OPERATOR_CANCEL step.
Specifies the processing ACMS does when a task is canceled.
CANCEL ACTION IS <processing-clause>
processing-clause
A processing clause that describes the work done when a task cancel occurs. Describe the work using a CALL, DATATRIEVE COMMAND, DCL COMMAND, or IMAGE processing clause. Each of these clauses is described in Section 3.6.
The CANCEL ACTION phrase is optional. If you do not specify a cancel action, ACMS does not perform any task-specific work when it cancels the task.
When a task instance is canceled, ACMS performs the work specified in the CANCEL ACTION phrase as the last step in the task cancellation sequence. If the task is retaining context in any server process when the task is canceled, ACMS calls the cancel procedure named in the CANCEL PROCEDURE subclause of the server definition before performing the CANCEL ACTION work. Because ACMS releases server context after calling a server cancel procedure, a task should not rely on the work specified in the CANCEL ACTION phrase being executed in a server process in which the task was retaining context.You can use workspaces when defining the cancel action for a block step if that cancel action uses a procedure server. ACMS keeps workspaces associated with a task until it is finished processing the cancel action for that task.
You cannot use the CANCEL ACTION phrase on a nested block.
You cannot use the CANCEL ACTION phrase on the root block of a composable task.
You cannot use a CALL TASK clause in a CANCEL ACTION phrase.
For an example of a cancel procedure, see Compaq ACMS for OpenVMS Writing Server Procedures.
BLOCK
WITH CANCEL ACTION
CALL DELETE_ORDER IN ORDER_SERVER
USING ORDER_DATA_REC
|
If this task is canceled, ACMS calls the DELETE_ORDER procedure in the server named ORDER_SERVER, and passes the ORDER_DATA_REC record to the procedure.
You do not end the CALL subclause with a semicolon (;) because it is part of the CANCEL ACTION phrase.
Stops the task in the action part of the current step by canceling the current task instance.
message-number
A literal number identifying a user-defined status value to be displayed when a task is canceled.numeric-workspace-field
A workspace field with a CDD signed longword data type. The contents of the field must be the binary longword equivalent of the message symbol for the message you want ACMS to display. ACMS uses the contents of the field to identify a message in one of the message files that can be accessed by the task group associated with the task. The workspace containing this field must be named in either the WORKSPACES or USE WORKSPACES clause in the task definition.global-symbol
A valid global symbol identifying a status value to be displayed when a task is canceled. The symbol is resolved to a longword value from the files specified by the /USERLIBRARY, /OBJECT, /SYSLIB, and /SYSSHR qualifiers of the BUILD GROUP command.
The CANCEL TASK clause is optional. If you do not use the CANCEL TASK clause, ACMS does not cancel the task unless it encounters unrecoverable errors. The default sequencing action for the last step within a block is EXIT BLOCK. The default sequencing action for all other steps within a block is GOTO NEXT STEP.
In the action part of a step, if you do not specify an exception code with the CANCEL TASK clause, ACMS cancels the task with a status of ACMS$_TASK_DEF_CANCELLED. In the exception handler part of a step, if you do not specify an exception code with the CANCEL TASK clause, ACMS cancels the task with the exception code associated with the current exception. If you specify an exception code, it must be a failure status. If you specify a success status, ACMS cancels the task and supplies a failure status after auditing the task cancellation, including the success status code, in the ACMS audit log.When you use the CANCEL TASK clause, the default transaction action for a step that starts a distributed transaction is ROLLBACK TRANSACTION. If you do not want ACMS to automatically roll back a distributed transaction when processing a CANCEL TASK clause, you can specify COMMIT TRANSACTION in the same action statement as that CANCEL TASK clause. You cannot specify a transaction action on a step within a step that starts a distributed transaction. Therefore, if you specify CANCEL TASK on a step within a distributed transaction, ACMS rolls back the distributed transaction.
If you have defined a cancel procedure for any servers in which the task is retaining context, ACMS executes the cancel procedures for those servers. If the task is not retaining context in any servers when ACMS executes the CANCEL TASK clause, ACMS does not call any cancel procedures.
You can specify the CANCEL ACTION clause in the action part of an exchange, processing, nested block, root processing, or root block step.
You can use the exception handler part of a step to control the execution of a parent task when a called task is canceled.
See Compaq ACMS for OpenVMS Writing Applications for information about controlling task cancellations.
PROCESSING WITH NONPARTICIPATING SERVER
CALL PROCEDURE VR_COMPUTE_BILL_PROC
IN VR_READ_SERVER
USING VR_RESERVATIONS_WKSP,
VR_RENTAL_CLASSES_WKSP;
ACTION IS
IF (ACMS$T_STATUS_TYPE = "B")
THEN
CANCEL TASK RETURNING ACMS$L_STATUS;
END IF;
|
This processing step calls the VR_COMPUTE_BILL_PROC procedure, then tests the ACMS$T_STATUS_TYPE field of the ACMS$PROCESSING_STATUS workspace. If the procedure completes successfully, control passes to the next step in the task. However, if the procedure does not complete successfully, the action part of the processing step directs ACMS to cancel the task and return the status from the ACMS$L_STATUS field.
Specifies whether or not a task can be canceled by a terminal user or task submitter. You can use a CANCELABLE clause to control how a terminal user or task submitter can exit a task. If a task is defined as NOT CANCELABLE, it cannot be canceled by pressing [Ctrl/Y] or[Ctrl/C].
The CANCELABLE clause is optional.All tasks are cancelable by default. If you do not use a CANCELABLE clause, a task can be canceled by either a terminal user or a task submitter.
REPLACE TASK MENU_TASK
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 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 STEP;
( WORK_RECORD.ENTRY EQ "EXIT"):
EXIT TASK;
NOMATCH:
REPEAT STEP;
END SELECT ;
END DEFINITION;
|
In this example, the task definition for MENU_TASK includes the NOT CANCELABLE clause. You cannot cancel MENU_TASK by pressing [Ctrl/Y] or [Ctrl/C] when it is executing.
Marks the end of a distributed transaction and makes permanent any file or database operations performed within the transaction.
COMMIT TRANSACTION;
The COMMIT TRANSACTION clause is optional. If you do not explicitly end a distributed transaction by specifying COMMIT TRANSACTION or ROLLBACK TRANSACTION, ACMS commits the transaction; however, if the action part of the step that started the distributed transaction specifies CANCEL TASK or RAISE EXCEPTION, ACMS rolls back the transaction.
You can specify COMMIT TRANSACTION in the action part of a root block, nested block, root processing step, or a processing step that is part of a multiple-step task. You can specify COMMIT TRANSACTION only in the action part of step that starts a distributed transaction.Because a distributed transaction must end in the action part of the step that starts the transaction, you cannot specify COMMIT TRANSACTION on a step within a 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 Section 3.9 and Compaq ACMS for OpenVMS Writing Applications for information on using the EXCEPTION HANDLER ACTION clause to recover from transaction failures.
Table 3-19 shows the default transaction actions for different situations in a task definition.
BLOCK WORK WITH DISTRIBUTED TRANSACTION
PROCESSING
CALL ENTER_ORDER IN DIST_CTR_DATABASE_UPDATE_SERVER
USING ORDER_ENTRY_RECORD, RESTOCK_RECORD;
PROCESSING
IF (ORDERED_AMOUNT > IN_STOCK_AMOUNT)
THEN CALL QUEUE_REPLENISH_INVENTORY_TASK IN QUEUE_SERVER
USING RESTOCK_RECORD;
END IF;
END BLOCK;
COMMIT TRANSACTION;
|
This example starts a distributed transaction on the block step, includes two processing steps, and ends the transaction in the action part of the block step with COMMIT TRANSACTION.
| Previous | Next | Contents | Index |