| Previous | Contents | Index |
Performs a step or action based on a condition. You can use a CONTROL FIELD clause to start a block, processing, or exchange step (thereby creating a conditional block, processing, or exchange step), or to start an action clause (thereby creating a conditional action clause).The CONTROL FIELD clause names a text field in a workspace, possible values for that field, and actions associated with each value. ACMS tests the named field and takes the action associated with the first value that matches the contents of that field. The NOMATCH keyword specifies an action to take if there is no match between the field and a value.
control-field
The name of a workspace field the CONTROL FIELD clause tests to determine what action to take. The field must be a text field and can be either in a workspace you define or in any one of the system workspaces.When you use the control-field parameter, you can name either just the field or the name of the workspace containing that field followed by a period (.) and the field name.
value
Either a quoted string or the keyword NOMATCH. Different actions are taken depending on the value in the named workspace field. If the value is a quoted string, that string must be no longer than the length of the field named by the control-field parameter. If the length of the quoted string is shorter than the length of the named field, ACMS fills the extra spaces of the string with blanks.ACMS does the processing associated with the NOMATCH keyword if none of the other values listed matches the contents of the named field. If you use the NOMATCH keyword, it must be the last value you list in the CONTROL FIELD clause.
clause
One of the following, depending on the placement of your CONTROL FIELD 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 and PROCESSING WORK, respectively. When you use the CONTROL FIELD clause at the block step level, you can specify multiple block, exchange, and processing steps for each value or NOMATCH you list.
At the block step level, you can use the CONTROL FIELD 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 that 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 each value or NOMATCH you list in the CONTROL FIELD clause.
processing-clause
Any unconditional processing clause. There can be only one processing clause for each value or NOMATCH you list in the CONTROL FIELD clause.
action-clause
Any unconditional action clause. ACMS provides four types of unconditional action clauses: workspace manipulation, transaction action, server context, and sequencing. For each value or NOMATCH you list in the CONTROL FIELD clause, you can specify one or both of the workspace manipulation clauses and one of each of the other three types of action clauses.
You can use action clauses at the end of a block, exchange, or processing step.
Table 3-11 and Table 3-12 summarize the clauses that you can use within the CONTROL FIELD clause in each step.
Table 3-12 lists the action clauses you can use with the CONTROL FIELD clause.
| 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: | |
|
|
|
| For each value or NOMATCH you list in the CONTROL FIELD clause, you can specify: | |||
|---|---|---|---|
| Workspace Actions | Transaction Actions | Server Context Actions | Sequencing Actions |
| Both: | One of: | One of: | One of: |
|
|
|
|
NOMATCH
Performs the actions in the clause if none of the values in the list matches the contents of the field being tested. The NOMATCH keyword must be the last value in the list. Do not enclose the NOMATCH keyword in parentheses.
The CONTROL FIELD clause is optional. If you do not use the CONTROL FIELD clause or one of the other three conditional clauses, ACMS processes your exchange, processing, or action clauses unconditionally.
End each subclause in a CONTROL FIELD clause with a semicolon (;), and end the CONTROL FIELD clause with END CONTROL FIELD and a semicolon (;).The type of clause you can use within a CONTROL FIELD clause depends on the type of step that you are defining. For example, if you are using CONTROL FIELD to define an exchange step, you can only use exchange clauses.
If you use CONTROL FIELD 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.
ACMS takes the action associated with the first value that matches the contents of the field named by the control field parameter.
Before comparing the contents of the control field and the values listed in a CONTROL FIELD clause, ACMS converts both strings to all uppercase, padding with blanks. For example, assume the control-field SAMPLE_FIELD contains space for two characters. If the field contains the character A, all of the following values are valid matches for the contents of that field: "A", "a", "A ", "a ", "A ", "a ".
A procedure in a processing step always returns a value to the ACMS$L_STATUS field of the ACMS$PROCESSING_STATUS system workspace. ACMS interprets that and stores values in the fields named ACMS$T_SEVERITY_LEVEL and ACMS$T_STATUS_TYPE. If you are testing the ACMS$PROCESSING_STATUS workspace, the control-field is normally either ACMS$T_SEVERITY_LEVEL or ACMS$T_STATUS_TYPE.The ACMS$T_SEVERITY_LEVEL field contains a single character severity level code for the return status contained in the ACMS$L_STATUS field. These codes are:
- S (Success)
- I (Information)
- W (Warning)
- E (Error)
- F
The ACMS$T_STATUS_TYPE field contains a single character code indicating whether the return status is good or bad. These codes are:
- G (GOOD)
- B (BAD)
The code "G" indicates the low bit is set in the field ACMS$L_STATUS, denoting an error severity level of SUCCESS or INFORMATION. The code "B" indicates the low bit is clear, denoting an error severity of WARNING, ERROR, or FATAL.
See Appendix B for further information on system workspaces.
A common use of the CONTROL FIELD clause in exchange steps is to test whether the terminal user wants to stop a running task. In DECforms, you can define a value associated with a function key so that whenever the terminal user presses that key, DECforms returns that value to a workspace field in ACMS. You can then test the field for that value by using the CONTROL FIELD clause in the action part of an exchange step.
| #1 |
|---|
BLOCK WORK
CONTROL FIELD PERS_WKSP.TEST_FIELD
"DISPLAY" : PROCESSING WORK
CALL ADD_EMPLOYEE IN PERSONNEL
USING WORKSPACE PERS_WKSP;
NOMATCH : PROCESSING WORK
NO PROCESSING;
EXIT BLOCK;
END CONTROL FIELD;
|
This CONTROL FIELD clause tests the contents of the TEST_FIELD field in the PERS_WKSP workspace. If the value of the field is "DISPLAY", ACMS processes the ADD_EMPLOYEE procedure. However, if TEST_FIELD contains any other value, denoted by the NOMATCH keyword, ACMS performs no processing work and exits from the block.
| #1 |
|---|
EXCHANGE
CONTROL FIELD TEST_RECORD.TEST_FIELD
"NUMBER" : NO EXCHANGE;
NOMATCH : RECEIVE RECORD EMPLOYEE_INFO_RECORD
RECEIVING EMPLOYEE_INFO_WKSP;
END CONTROL FIELD;
|
ACMS tests the contents of TEST_FIELD in the TEST_RECORD workspace being used by the task. If the value "NUMBER" is in that field, ACMS does not do any input or output, but goes on to process the next step in the definition. However, if TEST_FIELD contains any other value, denoted by the NOMATCH keyword, ACMS processes the RECEIVE operation and then goes on to process the next step in the definition.
| #1 |
|---|
PROCESSING
CONTROL FIELD PERS_WKSP.TEST_FIELD
"Y" : NO PROCESSING;
NOMATCH : CALL ADD_EMPLOYEE IN PERSONNEL
USING WORKSPACE PERS_WKSP;
END CONTROL FIELD;
|
In this example, the CONTROL FIELD clause tests the field TEST_FIELD in the PERS_WKSP workspace. If the value of that field is "Y", ACMS does not execute a processing step, but goes on to process the next step in the definition. If, however, TEST_FIELD contains any other value, denoted by the NOMATCH keyword, ACMS processes the ADD_EMPLOYEE procedure.
| #1 |
|---|
EXCHANGE
RECEIVE RECORD ADD_EMPLOYEE_RECORD
RECEIVING ADD_EMPLOYEE_WKSP
WITH RECEIVE CONTROL QUIT_RECORD;
CONTROL FIELD IS QUIT_RECORD.QUIT_KEY
" FQUT" : EXIT TASK;
END CONTROL FIELD;
|
In this example, if the user presses the PF1 key to exit from the task, the form that contains the ADD_EMPLOYEE_RECORD returns the value " FQUT" to the QUIT_KEY field of the QUIT_RECORD workspace. If " FQUT" is in that field when ACMS processes the CONTROL FIELD clause, ACMS exits from the task. Otherwise, ACMS goes on to process the next step in the definition.
| #2 |
|---|
PROCESSING
CALL ADD_EMPLOYEE IN PERSONNEL
USING PERS_RECORD, ADD_WORKSPACE;
CONTROL FIELD ADD_WORKSPACE.WK_CONTROL
"ERRORS" : GOTO PREVIOUS EXCHANGE;
END CONTROL FIELD;
END STEPS;
|
In this example, if the ADD_EMPLOYEE procedure encounters errors, it returns the value "ERRORS" to the WK_CONTROL field of the workspace ADD_WORKSPACE. The CONTROL FIELD clause tests that field. If the WK_CONTROL field contains the value "ERRORS", ACMS executes the previous exchange step in the definition. Otherwise, ACMS goes on to process the next step in the definition.
| #3 |
|---|
PROCESSING
CALL ADD_EMPLOYEE IN PERSONNEL
USING PERS_RECORD, ADD_WORKSPACE;
CONTROL FIELD ACMS$T_STATUS_TYPE
"B" : GET ERROR MESSAGE;
GOTO PREVIOUS EXCHANGE;
"G" : GOTO NEXT STEP;
END CONTROL FIELD;
END STEPS;
|
In this example, the ADD_EMPLOYEE procedure returns a status value. ACMS translates that value and stores either G or B in the ACMS$T_STATUS_TYPE field of ACMS$PROCESSING_STATUS. If the value "B" is in that field when the CONTROL FIELD clause tests it, ACMS gets an error message from the error message file, stores that message in the ACMS$T_STATUS_MESSAGE_LONG field, and executes the previous exchange step in the definition. If the value "G" is in the field, ACMS goes on to process the next step. GOTO NEXT STEP is the default sequencing action for steps within a block.
Names a DATATRIEVE command to do work for a processing step.
dtr-command-string
A valid DATATRIEVE command that cannot exceed 254 characters. You must enclose the string in quotation marks.server-name
The name of the server in which the DATATRIEVE command is executed. When you use the DATATRIEVE COMMAND clause, the server you name must be a DCL server and 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.
The DATATRIEVE COMMAND clause is optional; if you do not use it, ACMS does not invoke a DATATRIEVE command or procedure.
Any DATATRIEVE command you name must run in a DCL server.You can pass the contents of a selection string to a DATATRIEVE command in a processing step by using that string as a set of one or more parameters to the command. The selection string provided by the terminal user can be separated by ACMS into parameters P1 through P8. Each parameter is delimited by a space or tab. At run time, ACMS converts any unquoted alphabetic characters to uppercase. To include spaces or tabs in a parameter or to keep a character in lowercase, the terminal user encloses the string with double quotation marks. To include a double quotation mark character in the string itself, the terminal user must enclose that character in double quotation marks. ACMS does not treat exclamation marks or single quotation marks as special characters. Therefore, you do not have to enclose these characters in double quotation marks.
You can use parameters P1 through P8 in the DATATRIEVE command by including the parameter name in single quotes.
For more information on DCL command symbol substitution, see OpenVMS DCL Dictionary.
PROCESSING
DTR COMMAND IS
"DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES.DUE"
IN COMMON_UTILITY_SERVER;
|
This task runs a DATATRIEVE procedure named DUE. The procedure is stored in the ACMS$EXAMPLES directory. DISK1:[CDDPLUS] is the dictionary anchor. You must enclose the command string in quotation marks.
Names a DCL command to do work for a processing step.
DCL COMMAND IS dcl-command-string [ IN server-name ] ;
dcl-command-string
A valid DCL command that cannot exceed 254 characters beginning with the dollar sign ($) character. You must enclose the command string in quotation marks.server-name
The name of the server in which the DCL command is executed. When you use the DCL COMMAND clause, the server you name must be a DCL server declared in the task group. If you do not name a server, ACMS uses the server named in the DEFAULT SERVER clause in the task definition.
The DCL COMMAND clause is optional; if you do not use it, ACMS does not execute a DCL command to do work for a processing step.
Any DCL command you name must run in a DCL server.You can pass the contents of a selection string to a DCL command in a processing step by using that string as a set of one or more parameters to the command. The selection string provided by the terminal user can be separated by ACMS into parameters P1 through P8. Each parameter is delimited by a space or tab. At run time, ACMS converts any unquoted alphabetic characters to uppercase. To include spaces or tabs in a parameter or to keep a character in lowercase, the terminal user encloses the string with double quotation marks. To include a double quotation mark character in the string itself, the terminal user must enclose that character in double quotation marks. ACMS does not treat exclamation points or single quotation marks as special characters. Therefore, you do not have to enclose these characters in double quotation marks.
You can use parameters P1 through P8 in the DCL command by including the parameter name in single quotes.
For more information on DCL command symbol substitution, see OpenVMS DCL Dictionary.
Do not use the DCL INQUIRE command in a DCL command procedure that runs in a DCL server. The INQUIRE command requests the interactive assignment of a value for a local or global symbol during the execution of a command procedure. A DCL command procedure running in a DCL server that contains an INQUIRE command exits with an error status, and the task using the DCL server is canceled.
Instead, you can use the following command in a DCL procedure that runs in a DCL server:
$ READ/PROMPT=<prompt-string> SYS$COMMAND <data-item>For example:
$ READ/PROMPT="Enter dec number: " SYS$COMMAND P1If you use SET VERIFY in a command procedure that runs in a reusable server, make sure that the command procedure executes a SET NOVERIFY command before exiting. Otherwise, SET VERIFY remains in effect for the next server process user.
PROCESSING
DCL COMMAND IS "$EDIT/TPU 'P1'"
IN PRIVATE_UTILITY_SERVER;
|
This processing step uses the server PRIVATE_UTILITY_SERVER to execute a DCL command that invokes TPU. The command uses a parameter the user supplies as P1.
Names a default form used by the SEND, RECEIVE, and TRANSCEIVE clauses in exchange steps of a task.
DEFAULT FORM IS form-label-name;
form-label-name
The name assigned to the form using the WITH NAME keywords in the FORMS clause of the task group definition. The form-label-name uniquely identifies a form within a form file.
The DEFAULT FORM clause is optional. You can name, in the SEND, RECEIVE, or TRANSCEIVE clause of an exchange step, the form used by that step. If you do not specify the form in an exchange step and you do not use the DEFAULT FORM clause, ACMS uses the first form declared in the task group definition.
If you name a default form for a task, you must use the DEFAULT FORM clause before you define a block or processing step for that task.When you use the DEFAULT FORM clause, you do not have to name a form in individual exchange steps unless one of those steps uses a record from a different form.
If you name a form with the DEFAULT FORM clause, ACMS passes the name of that form to DECforms. If you do not use the DEFAULT FORM clause, and the form record is not specified in the exchange step of the task, ACMS passes the name of the first form specified in the task group definition.
You can specify a form label in the SEND, RECEIVE, or TRANSCEIVE clause of an exchange step to override a form named by the DEFAULT FORM clause.
DEFAULT FORM IS EMPLOYEE_INFO_FORM;
|
This names EMPLOYEE_INFO_FORM as the default form for this task. The exchange steps in this task use records from this form unless another form is specified in subsequent exchange steps.
| Previous | Next | Contents | Index |