HP OpenVMS Systems Documentation

Content starts here

Compaq ACMS for OpenVMS
ADU Reference Manual


Previous Contents Index


SHOW LOG (ADU>)

Displays information about logging, which you enable with the SET LOG command. Use this command to see if logging is taking place and to find the name of the file where you are logging data.

Format

SHOW LOG


Notes

If logging is not active, the SHOW LOG command displays a message about the current file specification. The SET LOG command uses that file specification the next time you enable logging, unless you name a new file.

Examples

#1

$ ADU
ADU> SET LOG
ADU> SHOW LOG
logging to file EXAMPLES$:[EXAMPLES]ADULOG
ADU> SET LOG LOGFILE.LOG
ADU> SHOW LOG
logging to file EXAMPLES$:[EXAMPLES]LOGFILE.LOG;1
ADU>
      

The SET LOG command uses the default file ADULOG.LOG in your default directory. The second SET LOG command includes a file name, LOGFILE.LOG. This file remains the log file until you either exit ADU or assign another file. Reassign the default log file ADULOG.LOG by naming that file again with the SET LOG command.

#2

$ ADU
ADU> SET LOG
ADU> SHOW LOG
logging to file EXAMPLES$:[EXAMPLES]ADULOG.LOG;1
ADU> SET NOLOG
ADU> SHOW LOG
not logging to file EXAMPLES$:[EXAMPLES]ADULOG.LOG;1
ADU> SET LOG
logging to file EXAMPLES$:[EXAMPLES]ADULOG.LOG;2
ADU>
      

This example shows that the SET LOG command increases the version number of the default log file each time you enable logging. The SHOW LOG command indicates when logging is active and when it is not.


SHOW VERSION (ADU>)

Displays the current software version number of ADU.

Format

SHOW VERSION


Note

The SHOW VERSION command displays the version number in the form:


ACMS ADU Vn.n

Examples

#1

$ ADU
ADU> SHOW VERSION
ACMS ADU V4.2
ADU>
      

In this example, the SHOW VERSION command displays the current ADU version number and returns control to the ADU> prompt.

#2

$ ADU
ADU> SHOW
Show what        : VERSION
ACMS ADU V4.2
ADU>
      

ADU displays a prompt when you press [Return] immediately after you enter the SHOW command. Enter the VERSION keyword to get a display of the current ADU version number.


SPAWN (ADU>)

Creates a subprocess of the current process and transfers control of your job to the subprocess. Use this command to leave ADU temporarily to perform other tasks without exiting ADU.

Format

SPAWN [command] [/qualifiers]

Command Qualifiers Defaults
/INPUT [=file-spec] /INPUT=SYS$INPUT
/[NO]LOGICAL_NAMES /LOGICAL_NAMES
/OUTPUT [=file-spec] /OUTPUT=SYS$OUTPUT
/NOOUTPUT
/PROCESS [=subprocess-name]
/[NO]SYMBOLS /SYMBOLS
/[NO]WAIT /WAIT

Parameter

command

The DCL command to be executed in the subprocess that the SPAWN command creates. After executing the DCL command, the subprocess ends and control returns to ADU. If you do not specify a command, ADU presents you with a DCL prompt.

Qualifiers

/INPUT [=file-spec]

Names a file containing DCL commands to be executed in the subprocess. If you do not specify an input file with the /INPUT qualifier, the subprocess accepts input from the terminal (SYS$INPUT).

If you specify input from both a command and a file, the subprocess executes the command first, then the file.

/[NO]LOGICAL_NAMES

Tells ADU to copy all the logical names of the parent process to the subprocess. It is faster to create a subprocess without copying the logical names.

The default is /LOGICAL_NAMES.

/OUTPUT [=file-spec]

/NOOUTPUT

Names the file to contain output from the subprocess that the SPAWN command creates. If you do not use the /OUTPUT qualifier, the subprocess directs output to the terminal (SYS$OUTPUT).

The /NOOUTPUT qualifier suppresses all output from the subprocess.

If you direct output to the terminal, specify the /NOWAIT qualifier to delay the display of output while you are entering commands.

By default, the subprocess sends output to the terminal.

/PROCESS [=subprocess-name]

Specifies the name of the subprocess to be created.

USERNAME_n is the default subprocess name if you do not include the qualifier.

/[NO]SYMBOLS

Tells the system whether or not to pass DCL global and local symbols to the subprocess.

The default is /SYMBOLS.

/[NO]WAIT

Controls whether or not the system waits until the current subprocess is completed before allowing more commands to be issued in the parent process.

Use the /NOWAIT qualifier with the /OUTPUT qualifier so output from the subprocess goes to a file, not your terminal. Otherwise, output from the subprocess interrupts output from your parent process.

The default is /WAIT.


Notes

Use the SPAWN command when you need to read mail, check the contents of an OpenVMS file, or run a different utility without exiting ADU. If you return to your ADU session by logging out of the subprocess, the subprocess is terminated. To return to your ADU session without terminating the subprocess, use the DCL ATTACH command. You can then return to your subprocess from ADU with the ADU ATTACH command.

Use the ADU SPAWN command the way you use the DCL SPAWN command.


Examples

#1

ADU> SPAWN
$
      

The SPAWN command creates a subprocess and transfers control of your job to that process.

#2

ADU> SPAWN TYPE VR_RENTAL_CLASSES_WKSP.CDO
!
!                       VR_RENTAL_CLASSES_WKSP.CDO
!
DEFINE RECORD AVERTZ_CDD_WKSP:VR_RENTAL_CLASSES_WKSP
  DESCRIPTION IS /* This workspace maps the fields in the */
                 /* RENTAL_CLASSES table in the VEHICLE_RENTALS */
                 /* database.  This is a small table that is used */
                 /* to keep track of the 3 AVERTZ types of vehicles -- */
                 /* economy, mid-size, and full-size.  This workspace */
                 /* is used to pass data between the forms and */
                 /* procedures. */.
        AVERTZ_CDD_FIELD:COUNTRY_ID.
        AVERTZ_CDD_FIELD:REQUESTED_RENTAL_CLASS_ID.
        AVERTZ_CDD_FIELD:DAY_RENTAL_RATE_AMT.
        AVERTZ_CDD_FIELD:WEEK_RENTAL_RATE_AMT.
        AVERTZ_CDD_FIELD:MONTH_RENTAL_RATE_AMT.
END RECORD.
ADU>
      

In this example, ADU creates a subprocess and executes the DCL command TYPE VR_RENTAL_CLASSES_WKSP.CDO. Because the SPAWN command does not include the /NOWAIT qualifier, ADU waits for the command to execute before returning control to the parent process, thus terminating the subprocess.

#3

ADU> SPAWN/NOWAIT/OUTPUT=LIST_FORM.LOG FDU LIST FORM PERSONNEL_FORM
ADU>
      

In this example, ADU creates a subprocess and executes the FDU command LIST FORM PERSONNEL_FORM in that process. The /NOWAIT qualifier allows you to issue commands to ADU without waiting for the subprocess to complete. The /OUTPUT qualifier specifies that output from the FDU command is written to the LIST_FORM.LOG file.


Chapter 2
%INCLUDE

Many definitions share common parts. For example, suppose you always include certain default characteristics in an application definition. Instead of rewriting the same part of a definition many times, you can use %INCLUDE to put the contents of a file in a source definition.


%INCLUDE

Includes the contents of a file in a source definition. The %INCLUDE directive saves you from repeating clauses you use in many definitions; you can place the clauses in a file and use %INCLUDE to bring them into the source definition.

Format

%INCLUDE "file-spec"


Parameter

file-spec

The name of the file containing the information you want to include in another definition. You must enclose the file specification in quotation marks (" "). The default file type is .COM. If you do not name a device and directory, ACMS searches your default device and directory for the file you name.

Notes

The percent sign (%) differentiates %INCLUDE from definition keywords, component names, and component identifiers you can use in the definition.

Text in a file that you want to include in a definition at a later time must follow the same syntax rules as it would if it were part of the source at that point in the definition.

The %INCLUDE directive can appear on any line before the END DEFINITION keywords.

If you have used the SET LOG command, ADU puts the text of the include file in the log beginning with !%INC<!CLOSE>.

If you specify that a list file be created, ADU puts the text of the file named with %INCLUDE and any associated error messages in the list file. It also shows that the text originated from the included file.


Example


ADU> CREATE APPLICATION PERSONNEL
ADUDFN> %INCLUDE "PERSAPPL.COM"
      

In this example, ACMS uses the contents of the PERSAPPL.COM file in the current default device and directory to create the definition for the Personnel application.


Chapter 3
Task Definition Clauses

This chapter explains the ADU clauses you use to write task definitions. You use these clauses with the CREATE, MODIFY, REPLACE, or EDIT commands.

A task definition is made up of clauses describing the attributes of a task and the work done when a user selects a task. Task attribute clauses can define either the implementation characteristics or the control attributes of a task.

Task attribute clauses describe general characteristics of a task such as the workspaces used by task steps or a default server that handles processing work. You can override some characteristics by specifying the same clause with a different attribute in a step definition.

The work part of a task is defined in either a processing step or a block step made up of processing and exchange steps. You can define a single-step task or use the BLOCK WORK clause to define multiple-step tasks. Table 3-1 lists the task clauses and gives a brief description of each.

Table 3-1 Task Clauses
Clause Description
Task Implementation Attribute Clauses
DEFAULT FORM Names a default DECforms form used by the SEND, RECEIVE, and TRANSCEIVE clauses in exchange steps of a task
DEFAULT REQUEST LIBRARY Names a default TDMS request library used by exchange steps in a task
DEFAULT SERVER Names a default server to handle processing steps and canceling actions in a task
USE WORKSPACES Names one or more group-level workspaces the task uses
WORKSPACES Declares one or more workspaces used by steps in the task
Task Control Attribute Clauses
DELAY Causes a three-second delay before ACMS clears the final screen the task displays
WAIT Causes ACMS to wait for the user to press [Return] before clearing the final screen a task displays
Task-Call-Task Attribute Clauses
GLOBAL Specifies that a task can either be selected from a menu or called by another task
LOCAL Specifies that a task can be called by or chained to another task, but cannot be selected from a menu
CANCELABLE Specifies whether a task can be canceled by a task submitter
TASK ARGUMENTS Specifies the list of workspaces that are passed to a task during a Task-Call-Task operation or by an agent calling a task
Task Work Clauses
BLOCK Describes, in terms of block, exchange, processing, and action clauses, the work done in a block step
EXCHANGE Describes the work done to interact with the terminal user, typically through DECforms form records
PROCESSING Describes the computation and database I/O work that the task performs

Figure 3-1 shows the syntax you use to define a task.

Figure 3-1 Task Syntax


If a task consists of a single processing step, you must use the PROCESSING clause in the task definition to describe the work done by the task. However, if the task contains multiple steps or an exchange step, you must use the BLOCK clause to describe the work done by the task. You can use an EXCHANGE clause only within a block step.

The following examples illustrate how to use the clauses described in this chapter to write task definitions. Example 3-1 shows the definition for a single-step task. The definition for the task is stored in the dictionary as DTR_TASK in the default CDD directory.

Example 3-1 Simple Task Definition (Single-Step)

REPLACE TASK DTR_TASK
  DELAY;
  PROCESSING IS DCL COMMAND "MCR DTR32" IN UTILITY_SERVER;
END DEFINITION;

When a user selects this task from a menu, ACMS processes the DCL command MCR DTR32, which runs DATATRIEVE. Because this is a DCL command, the task must run in a DCL server. You can also define single-step tasks that use procedure servers. The DELAY clause causes ACMS to wait 3 seconds before clearing the final screen of the task and returning the user to a selection menu.

Note

Although you can write single-step task definitions, it is more efficient to use multiple-step tasks. ACMS also lets you define single-step processing tasks in the task group definition. Example 4-1 shows how to do this.

Example 3-2 shows an example of a multiple-step task definition. REVIEW_SCHEDULE_TASK is an inquiry task that lets the terminal operator view employees' performance review schedules.

The task definition contains three steps grouped into a block step. The workspaces REVIEW_SCHEDULE_WKSP and CONTROL_WKSP are available to all the steps in the block. The default form that contains the form records used by exchange steps in the block is DEPART_FORM. The keywords BLOCK WORK signal the beginning of the work done in the block. FORM I/O indicates that the exchange steps in the block use DECforms as the interface to the terminal operator.

Example 3-2 More Complex Task Definition (Multiple-Step)

REPLACE TASK REVIEW_SCHEDULE_TASK

  DEFAULT FORM IS DEPART_FORM;
  WORKSPACES ARE REVIEW_SCHEDULE_WKSP, CONTROL_WKSP;

  BLOCK
    WORK WITH FORM I/O

(1)GET_DEPT_NUMBER:
       EXCHANGE
       TRANSCEIVE FORM RECORD REVIEW_SCHEDULE_REC,
                              REVIEW_SCHEDULE_REC
           SENDING REVIEW_SCHEDULE_WKSP
           RECEIVING REVIEW_SCHEDULE_WKSP
           WITH RECEIVE CONTROL CONTROL_WKSP;
         CONTROL FIELD IS CONTROL_WKSP.CTRL_KEY
           " FEXT"    : EXIT TASK;
         END CONTROL FIELD;

(2)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;
         END CONTROL FIELD;

(3)DISPLAY_EMPLOYEES:
       EXCHANGE
         SEND FORM RECORD REVIEW_SCHEDULE_REC
           SENDING REVIEW_SCHEDULE_WKSP
           WITH RECEIVE CONTROL CONTROL_WKSP;
         CONTROL FIELD IS CONTROL_WKSP.CTRL_KEY
           " FMOR"    : GOTO PREVIOUS PROCESSING;
           " FEXT"    : EXIT TASK;
         END CONTROL FIELD;

   END BLOCK WORK;
   ACTION
     REPEAT TASK;
 END DEFINITION;

The following numbered explanations correspond to the numbers in Example 3-2:

  1. This exchange step uses the REVIEW_SCHEDULE_REC form record to display a panel asking the operator for the number of the department whose schedule of performance reviews they want to see.
  2. This processing step uses the REVIEW_SCHEDULE_GET procedure to retrieve the performance review schedules for the first five employees in the department. The server that the step uses is defined in the task group.
  3. This exchange step uses the REVIEW_SCHEDULE_REC form record to display the performance review schedules. The operator can type a function key to see the schedules for five more employees, or can exit the task. The keywords END BLOCK WORK signal the end of the work done in the block.

Action clauses follow block, exchange, and processing steps and control the flow of work within a task. The exchange and processing steps in this example use the CONTROL FIELD action clause which tests a workspace field and directs task flow depending on the results of the test. The block step in this example uses the REPEAT TASK action clause which causes ACMS to repeat the task. This particular task repeats until the CTRL_KEY field contains " FEXT".

You can define tasks as local or global. Global tasks are the default and can be chained to or called by another task or selected from a menu. Local tasks can be chained to or called by another task, but cannot be selected from a menu.

For security reasons, you might want to define a task as local if the task implements its own customer-specific task selection security and does not rely on the ACMS task access control list mechanism.

3.1 Multiple-Step Task Definitions

When a task definition has multiple steps or an exchange step, you always group those steps into a block step. A block step consists of the following five parts:

  • Attributes of the block step
  • A conditional to start the block step
  • Work done in the block step
  • Actions taken as a result of the work done in the block step
  • Exception handler actions to recover from task execution errors

You use phrases and clauses to describe each of these parts. Block phrases describe attributes of a block step. Unlike clauses and subclauses, phrases do not end in a semicolon (;). All block phrases are optional.

The work of a block step is made up of one or more processing and exchange steps. Use exchange and processing clauses to describe the work.

You can use block conditional clauses to make initial exchange and processing work dependent on the values of workspace fields.

Use action clauses to describe actions you want to take at the end of a block step, exchange step, or processing step. Action clauses are optional in all step definitions.

Exception handler action clauses let you recover from events or errors that would otherwise prevent the task from executing as expected. Exception handler action clauses are optional in all step definitions.

Figure 3-2 shows the structure of a block step.

Figure 3-2 Block Step Structure



Previous Next Contents Index