HP OpenVMS Systems Documentation

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 VMS Run-Time Library Routines Volume for more information.

For more information on DCL command symbol substitution, see Guide to Using VMS Command Procedures.

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.

Names a procedure that runs when a procedure server image is started. An initialization procedure performs such activities as opening files used by the procedures handled by a server.

Format

Parameter

initial-procedure-entry-name

The entry point name of the initialization procedure called in the procedure server image.

Clause Default

The INITIALIZATION PROCEDURE subclause is optional. If you do not name an initialization procedure, ACMS does not run any procedures when the procedure server image is started.

Notes

You can use the INITIALIZATION PROCEDURE subclause only when defining a procedure server.

The initialization procedure for a server runs only when the server process is started; it does not run when each task using the server runs or when each processing step using the server runs. However, servers can be started at any time while the application is starting or is started, depending on the processing load of the application.

When you name an initialization procedure for a procedure server, you normally also name a termination procedure for that server.

You can name only one initialization procedure for each server you define.

You can name the initialization procedure for a server in the PROCEDURES subclause for that server. However, you must also name the procedure with the INITIALIZATION PROCEDURE subclause.

Example

SERVER IS
  DEPARTMENT_SERVER:
    PROCEDURE IMAGE IS "ACMS$EXAMPLES:DEPARTGRP.EXE";
    INITIALIZATION PROCEDURE IS DEPART_STARTUP;
    TERMINATION PROCEDURE IS DEPART_SHUTDOWN;
    PROCEDURES ARE
      REVIEW_HISTORY_GET,REVIEW_SCHEDULE_GET, REVIEW_UPDATE_GET;
END SERVER;


      

When DEPARTMENT_SERVER is started, ACMS runs the initialization procedure whose entry point in the procedure server image is DEPART_STARTUP.

Names the message files used by the GET ERROR MESSAGE clause in the definitions of tasks in a task group.

Format

Parameter

message-file-spec

An identifier or quoted string pointing to the location of a message file with an .EXE file type. 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 .EXE. If you name more than one message file, use commas to separate the file specifications.

Clause Default

The MESSAGE FILES clause is optional. However, if your application uses user-defined error message files and uses the GET ERROR MESSAGE clause in task definition, you must name the message files used by those tasks. If you do not name any error message files, ACMS uses only the OpenVMS system message file.

Notes

Because the application execution controller loads all the message files for an application, message codes for different task groups must not conflict.

The message files you name with the MESSAGE FILES clause must be available at run time.

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

Do not confuse task group message files with global symbols used in a task definition GET ERROR MESSAGE clause. ACMS cannot resolve these global symbols to task group message files unless the message files are part of an object module or user-specified object library, or a shared image library. The symbols are then resolved by the /OBJECT or /USERLIBRARY qualifiers of the BUILD GROUP command.

See Compaq ACMS for OpenVMS Writing Server Procedures for information on creating message files for ACMS applications.

Examples

MESSAGE FILE IS "ACMS$EXAMPLES:DEPARTMSG.EXE";
      

The name of the message file is DEPARTMSG.EXE. The file is in the directory associated with the logical name ACMS$EXAMPLES.

MESSAGE FILE IS DEPARTMSG;
      

This example defines the error message file as the file associated with the DEPARTMSG logical name. DEPARTMSG is an identifier and does not require quotation marks. However, because all the characters in DEPARTMSG are valid for an OpenVMS file specification, DEPARTMSG can be a file name.

Identifies a server as a procedure server and names the procedure server image that does processing work for one or more tasks.

Format

PROCEDURE SERVER IMAGE IS procedure-image-file-spec;

Parameter

procedure-image-file-spec

The file specification of the .EXE file created by linking the following modules:

• Object module created as a result of building the task group containing that server
• Object modules of the procedures handled by that server including step procedures, cancel procedures, and initialization and termination procedures
• Object modules for message files named in the task group definition

The procedure image file can be either a file specification enclosed in quotation marks or an identifier. The default file type is .EXE. The default device and directory are those of the server.

Clause Default

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

Notes

Use the PROCEDURE SERVER IMAGE subclause only to define a procedure server.

All processing work done in a procedure server must be done using the CALL clause or subclause.

Any procedure server images you name with the PROCEDURE SERVER IMAGE subclause must be available at run time. In addition, any files used by those images must be available.

Example

SERVER IS
  DEPARTMENT_SERVER
    PROCEDURE IMAGE IS "ACMS$EXAMPLES:DEPARTGRP.EXE";
    INITIALIZATION PROCEDURE IS DEPART_START;
    TERMINATION PROCEDURE IS DEPART_STOP;
    PROCEDURES ARE
      REVIEW_HISTORY_GET,REVIEW_SCHEDULE_GET,REVIEW_UPDATE_GET;
END SERVER;
      

The name of the file containing the executable image associated with DEPARTMENT_SERVER is DEPARTGRP.EXE. The file is in the directory associated with the logical name ACMS$EXAMPLES.

Names the step procedures that can run in a procedure server.

Format

Parameter

entry-name

The entry point of a procedure in the procedure server image. If you name more than one procedure, separate the entry names with commas.

Clause Default

The PROCEDURES subclause is required for each procedure server you name in a task group. You must name at least one procedure for each procedure server.

Notes

Use the PROCEDURES subclause only when defining a procedure server.

Each procedure named in a CALL processing clause or subclause must be named in the PROCEDURES subclause for a procedure server.

You can include the name of any cancel procedure, initialization procedure, or termination procedure you define for the server in the PROCEDURES subclause for that server. If you have a large number of procedures in a procedure server, you can include more than one PROCEDURES subclause in the procedure server definition. All entry points are included in the server definition that ADU creates.

Examples

SERVER IS
  DEPARTMENT_SERVER
    PROCEDURE IMAGE IS "ACMS$EXAMPLES:DEPARTGRP.EXE";
    INITIALIZATION PROCEDURE IS DEPART_START;
    TERMINATION PROCEDURE IS DEPART_STOP;
    PROCEDURES ARE
      REVIEW_HISTORY_GET,REVIEW_SCHEDULE_GET,REVIEW_UPDATE_GET;
END SERVER;

      

Three procedures can be used in DEPARTMENT_SERVER. The entry points of these procedures in the procedure server image are REVIEW_HISTORY_GET, REVIEW_SCHEDULE_GET, and REVIEW_UPDATE_GET.

SERVERS ARE
  DIMS_SERVER:
    INITIALIZATION PROCEDURE IS DIMS_UPDATE_STARTUP;
    TERMINATION PROCEDURE IS DIMS_UPDATE_STOP;
    CANCEL PROCEDURE IS UPDATE_CANCEL;
    PROCEDURES ARE
      CHECK_BOM, CHECK_BOM_KIT, CHECK_COMP_PART_NUM, CHECK_DELETE,
      CHECK_KIT_PART_NUM, CHECK_PCS_PART_NUM, CHECK_USED_ON_COMP,
      CHECK_USED_ON_KITS, CLEAR_BOM_RECORDS, CLEAR_DELETE_RECORDS,
      CLEAR_KIT_RECORDS, CLEAR_PCS_RECORDS, CLEAR_PROMPT_STRING;
    PROCEDURES ARE
      CLEAR_RECORDS, CLEAR_REVIEW_RECORDS, CLEAR_SUS_LINK_REV_RECORDS,
      CLEAR_USED_ON_RECORDS, DELETE_RECORD, GET_BOM, GET_USED_ON,
      LOAD_BOM, LOAD_USED_ON_KITS, READ_SUS_LINK_FILE, READ_SUSPENSE_FILE,
      REWRITE_SUSPENSE_FILE, REWRITE_SUS_LINK_REC, REWRITE_SUSPENSE_REC;

    PROCEDURES ARE
      START_SUSPENSE_FILE, START_SUSPENSE_LINKAGE_FILE,
      WRITE_SUSPENSE_FILE, WRITE_KIT_SUSPENSE_FILE, WRITE_LINK_SUS,
      WRITE_MODIFIED_BOM, WRITE_MODIFIED_KIT, WRITE_MODIFIED_PCS,
      WRITE_PCS_SUSPENSE_FILE, WRITE_USED_ON_LINK_SUS;
  END SERVER;

      

Thirty-seven procedures can be used in DIMS_SERVER. The entry points of these procedures in the procedure server image are listed in three separate PROCEDURES subclauses.