Runs a DATATRIEVE command to do work for a processing step.

Format

Parameters

dtr-command-string

A valid DATATRIEVE command not exceeding 254 characters. Enclose the command string in quotation marks.

server-name

The name of the server in which the DATATRIEVE command is executed. When you use the DATATRIEVE COMMAND subclause, 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 last server named in the immediately preceding SERVERS clause.

Clause Default

The DATATRIEVE COMMAND processing subclause is optional; if you do not use it, ACMS does not run a DATATRIEVE command or procedure. However, if you are defining a task directly in a task group definition, you must include the CALL, DATATRIEVE COMMAND, DCL COMMAND, or IMAGE processing subclause within the TASKS clause.

Notes

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 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 DATATRIEVE command by including the parameter name in single quotes.

For more information on DCL command symbol substitution, see OpenVMS User's Manual.

If you want to invoke DATATRIEVE using a command other than MCR DTR32, define a logical using the LOGICALS clause in the server definition.

Example

TASK IS DUE: PROCESSING 
               DTR COMMAND IS "DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES.DUE" 
                 IN COMMON_UTILITY_SERVER; 
END TASK; 
 
      

The DUE task runs a DATATRIEVE procedure named DUE. The procedure is stored in the ACMS$EXAMPLES directory pointed to by the dictionary anchor, DISK1:[CDDPLUS]. Enclose the command string in quotation marks. The server named COMMON_UTILITY_SERVER is a DCL server.

Allows procedure servers to use the DIGITAL Command Language (DCL). DCL AVAILABLE allows you to specify the loading of DCL into a procedure server process.

Format

[ NO ] DCL AVAILABLE;

Clause Default

The DCL AVAILABLE subclause is optional. NO DCL AVAILABLE is the default. This means that DCL is, by default, not mapped into the procedure server process.

Notes

The DCL AVAILABLE subclause allows other software products, such as VIDA for DB2, to use DCL from within a procedure server. VIDA for DB2 is client/server software that makes IBM DB2 databases readable from OpenVMS systems.

This DCL AVAILABLE subclause applies to procedure servers only. It is not valid for DCL servers.

Note that mapping DCL into a procedure server process might have some effects on process quotas and the length of time that it takes to start the process.

The DCL AVAILABLE subclause is not supported when you use the ACMS debugger to debug a server image that is linked with PCA. If you fail to observe this restriction, the ACMS debugger displays a message similar to the following:

SERVER <server-name> stopped unexpectedly

Example

SERVER IS 
  DEPARTMENT_SERVER: 
    PROCEDURE SERVER IMAGE IS "ACMS$EXAMPLES:DEPREMSCOB.EXE"; 
    DCL AVAILABLE; 
   .
   .
   .
END SERVER; 
 
      

In this example, the DCL AVAILABLE subclause maps DCL to the procedure server process created for the procedure server DEPARTMENT_SERVER.

Uses a DCL command to process a task.

Format

DCL COMMAND [ IS ] dcl-command-string [ IN server-name ] ;

Parameters

dcl-command-string

A valid DCL command not exceeding 254 characters beginning with the dollar sign ($) character. Enclose the string in quotation marks.

server-name

The name of the server in which the DCL command is executed. When you use the DCL COMMAND subclause, 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 last server named in the immediately preceding SERVERS clause.

Clause Default

The DCL COMMAND processing subclause is optional; if you do not use it, ACMS does not run a DCL command or command procedure. However, if you are defining a task directly in a task group definition, include the CALL, DATATRIEVE COMMAND, DCL COMMAND, or IMAGE processing subclause within the TASKS clause.

Notes

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 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 DCL command by including the parameter name in single quotes.

For more information on DCL command symbol substitution, see OpenVMS User's Manual.

Examples

TASK IS EDT: PROCESSING DCL COMMAND IS "$EDIT/EDT 'P1'" 
               IN PRIVATE_UTILITY_SERVER; 
END TASK; 
      

This task uses the server PRIVATE_UTILITY_SERVER to execute a DCL command that invokes EDT. The command uses, as P1, a parameter the user supplies as a selection string.

TASK IS COPY: PROCESSING 
                DCL COMMAND IS "$COPY 'P1'.TXT 'P2'.TXT" 
                  IN PRIVATE_UTILITY_SERVER; 
END TASK; 
      

This task invokes the DCL COPY command. In this example, the name of the task on the menu is COPY. Suppose the user selects the task and types the following in response to the "Selection:" prompt:

Selection:COPY NAME1 NAME2

The command processed by the COPY task is:

COPY NAME1.TXT NAME2.TXT

Indicates that a server processes tasks that use DCL commands or command procedures, DATATRIEVE commands or procedures, or OpenVMS images.

Format

DCL PROCESS ;

Clause Default

You must identify a server type as either a DCL PROCESS or a PROCEDURE SERVER IMAGE.

Notes

A DCL server can be reusable.

All processing work done in a DCL server must be done by a DCL command or command procedure, a DATATRIEVE command or procedure, or an OpenVMS image.

If a task is processing in a DCL server, the DCL server always runs down when the task is canceled.

Example

SERVERS ARE 
  PRIVATE_UTILITY_SERVER: DCL PROCESS; 
                          DYNAMIC USERNAME; 
  COMMON_UTILITY_SERVER: DCL PROCESS; 
END SERVERS; 
      

Both the PRIVATE_UTILITY_SERVER and COMMON_UTILITY_SERVER are DCL servers; they handle the work done by DCL commands or command procedures, DATATRIEVE commands or procedures, or OpenVMS images.

Specifies a file name for the object module produced for a procedure server when you build the task group containing that server.

Format

DEFAULT OBJECT FILE IS object-file-spec ;

Parameter

object-file-spec

The file specification of the object file created for the server by the BUILD GROUP command. This object file contains the main entry point in the procedure server. The object file specification is either an identifier or a quoted string. The default file type is .OBJ. The default device and directory are your default device and directory when you build the task group.

Clause Default

The DEFAULT OBJECT FILE subclause is optional. If you do not name an object file, ACMS derives the name of the object file from the full given name of the server, including dollar signs ($) and underscores (_).

Note

You can use the DEFAULT OBJECT FILE clause only when defining a procedure server.

Example

SERVER IS 
  PERSONNEL_SERVER: PROCEDURE IMAGE IS "PERSGRP.EXE"; 
                    PROCEDURE IS PERSADD; 
                    DEFAULT OBJECT FILE IS "PERSERVER.OBJ"; 
END SERVER; 
      

When you build the task group containing this server, ACMS produces the object file PERSERVER.OBJ for the procedure server PERSONNEL_SERVER.

Names the default file specification of the task group database.

Format

DEFAULT TASK GROUP FILE IS task-group-database-file ;

Parameter

task-group-database-file

The file specification of the task group database file. When you build a task group definition, ACMS produces a database for that group. The file specification for that database can be either an identifier or a quoted string. The default file type is .TDB. The default device and directory is your current default device and directory.

Clause Default

The DEFAULT TASK GROUP FILE clause is optional. If you name a task group database file when you build a task group, ACMS uses that name to override any task group database file you name with the DEFAULT TASK GROUP FILE clause.

If you do not name a task group database file when you build a task group, and you do not name a database file with the DEFAULT TASK GROUP FILE clause, ACMS derives the default database file specification from the full given name of the task group, including dollar signs ($) and underscores (_).

Note

If you include a database file name when you build the task group, ACMS uses that name and overrides any file you name in the DEFAULT TASK GROUP FILE clause.

Examples

DEFAULT TASK GROUP FILE IS "SYS$SAMPLE:PERSONNEL.TDB"; 
      

The task group database file is PERSONNEL.TDB in the directory associated with the logical name SYS$SAMPLE. The file specification in this example includes a colon (:) and a period (.). These characters are not valid for an identifier. Therefore, you must enclose the file specification in quotation marks.

GROUP FILE IS PERSONNEL; 
      

The task group database file is PERSONNEL with a default .TDB file type. The device and directory default to the current default device and directory. PERSONNEL is a valid identifier; you do not need to enclose it in quotation marks.

Specifies that the user name, UIC, and default directory of a server change to match those of the task submitter each time the server process is used.

Format

DYNAMIC USERNAME ;

Clause Default

The DYNAMIC USERNAME subclause is optional. The default is the control attribute defined for the server in the application definition.

Notes

If you define a server to have a dynamic user name, ACMS changes the user name, UIC, and default directory to those of the task submitter. In addition, the logical names SYS$LOGIN and SYS$SCRATCH are defined to be the full default directory.

The DYNAMIC USERNAME clause is not valid for procedure servers. If you use the clause with a procedure server, ADU accepts the clause. However, the user name is not changed at run time when users select tasks that run in that server. Instead, the server keeps the user name under which it was started.

If you do not assign a specific user name to the server in the application definition, but use the APPLICATION USERNAME clause, ACMS assigns the user name of the application to the server when it starts up. If you assign a specific user name to the server with the USERNAME clause in the application definition, ACMS assigns that name to the server when it starts up. In both these cases, the user name changes if you define the server to have a dynamic user name.

You cannot combine the USERNAME OF TERMINAL USER and DYNAMIC USERNAME subclauses.

When a server process is created, it uses the group logical name table for the UIC that corresponds to the user name with which the server is created. This group logical name table remains in use for the life of the server process. For servers with dynamic user names, the group logical name table does not change if the user name changes and the corresponding UIC is in a different group.

Servers defined with the DYNAMIC USERNAME subclause do not restore the initial user name before running down. Therefore, the OpenVMS accounting facility will charge the resources used by the server to the last user who selected a task in that server instance. However, the correct ACCOUNT field is used because ACMS does not modify that field in the process header.

Example

SERVER IS 
  PERSONNEL_SERVER: DCL PROCESS; 
                    REUSABLE; 
                    DYNAMIC USERNAME; 
END SERVER; 
      

PERSONNEL_SERVER is a reusable DCL server with a dynamic user name.

Specifies that the user name, UIC, and default directory of the server are those associated with the user name under which the server starts.

Format

FIXED USERNAME ;

Clause Default

The FIXED USERNAME clause is optional. The default is the control attribute defined for the server in the application definition.

Note

If you define a server to have a fixed user name, the server always keeps the same user name, UIC, and default directory under which it started.

Example

SERVER IS 
  PERSONNEL_SERVER: DCL PROCESS; 
                    REUSABLE; 
                    FIXED USERNAME; 
END SERVER; 
      

PERSONNEL_SERVER is a reusable DCL server with a fixed user name.

Names the forms the task group uses.

Format

Parameters

form-name

The name of the form that the tasks within the task group use. You can store multiple forms in a form file.

form-file-spec

An identifier or quoted string pointing to the location of a DECforms form file or shared image file. The default device and directory are those defined with the application-level DEFAULT DIRECTORY clause in the definition of the application containing the task group. The default file type is .FORM for a DECforms form file and .EXE for a shared image file.

form-label-name

A 1- to 31-character identifier you assign to the form with the WITH NAME keywords. Tasks in the task group refer to a form by its form label name. You must assign a form label name to each form.

If you do not name a form or a default form in a task definition, ACMS uses the first form named in the task group definition containing that task.

Clause Default

The FORMS clause is required if any of the tasks in the task group use DECforms forms called by exchange steps. If you do not name any forms, ACMS does not make any forms available to the task group.

Notes

You can use the FORMS clause more than once in a single task group definition.

The forms you name with the FORMS clause must be available at run time. If the task group contains tasks that are accessed remotely, the UIC-based file protection on the form files you name with the FORMS clause must grant world read access.

The form-file-spec parameter cannot be a search list.

Example

FORMS ARE 
   EMPLOYEE_INFO IN "UNODE::UDEVICE:[UNAME.NEW_PERS]EMPLOYEE_INFO" 
      WITH NAME EMPLOYEE_INFO_LABEL, 
   JOB_SALARY_INFO IN "UNODE::UDEVICE:[UNAME.NEW_PERS]EMPLOYEE_INFO" 
      WITH NAME JOB_SALARY_LABEL; 
      

Each task in the task group uses a form label name to refer to the form it uses. In this example, the unique form label names are EMPLOYEE_INFO_LABEL and JOB_SALARY_LABEL.

Names the OpenVMS image that ACMS runs when users select an image task.

Format

IMAGE IS image-file-spec [ IN server-name ];

Parameters

image-file-spec

The file specification of the OpenVMS image you want to run. A file specification is either an identifier or a quoted string pointing to the location of the file. The default file type is .EXE. The default device and directory are those defined for the server as control attributes in the application definition.

server-name

The name of the server in which the image is executed. When you use the IMAGE subclause, 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 last server named in the immediately preceding SERVERS clause.

Clause Default

The IMAGE processing subclause is optional; if you do not use it, ACMS does not run an OpenVMS image. However, if you are defining a task directly in a task group definition, you must include the CALL, DATATRIEVE COMMAND, DCL COMMAND, or IMAGE processing subclause within the TASKS clause.

Notes

Any image you name must run in a DCL server.

You can pass the contents of a selection string to an image 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.

The image can access parameters P1 through P8 by using the OpenVMS Run-Time Library routine that accesses DCL symbols. This routine is LIB$GET_SYMBOL. See OpenVMS RTL Library (LIB$) Manual for more information.

For more information on DCL command symbol substitution, see OpenVMS User's Manual.

Example

TASK IS DATR: PROCESSING 
                IMAGE IS "SYS$SYSTEM:DTR32" 
                  IN COMMON_UTILITY_SERVER; 
END TASK; 
      

The DATR task uses the server COMMON_UTILITY_SERVER to invoke an OpenVMS image that runs DTR32.