# Compaq ACMS for OpenVMS
ADU Reference Manual

Previous | Contents | Index

# INITIALIZATION PROCEDURE Subclause (Server)

> 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.

# MESSAGE FILES Clause (Task Group)

> 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

#1
    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.

#2
    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.

# PROCEDURE SERVER IMAGE Subclause (Server)

> 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.

# PROCEDURES Subclause (Server)

> 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

#1
    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.

#2
    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.

# REQUEST LIBRARIES Clause (Task Group)

> Names the request libraries the task group uses.

## Format

## Parameters

> ### request-library-file-spec

> An identifier or quoted string pointing to the location of a TDMS request library or Request Interface user request procedure 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 .RLB for a TDMS request library and .EXE for a Request Interface user request procedure shared image file.

> ### library-name

> A 1- to 31-character identifier you assign to the request library with the WITH NAME keywords. Tasks in the task group refer to a request library by its library name. If you name more than one request library in a task group definition, you must assign a library name to each library. However, if you name only one request library, you do not have to assign a library name to that library. In this case, the default name of the request library is the request library file specification.

> If you do not name a request library in a task definition, the request library defaults to the first request library named in the task group definition containing that task.

## Clause Default

> The REQUEST LIBRARIES clause is required if any of the tasks in the task group use TDMS requests called by exchange steps. If you do not name any request libraries, ACMS does not make any request libraries available to the task group.

## Notes

> You can use the REQUEST LIBRARIES clause more than once in a single task group definition.

> The request libraries you name with the REQUEST LIBRARIES clause must be available at run time. If the task group contains tasks that are accessed remotely, the UIC-based file protection on the request library files you name with the REQUEST LIBRARIES clause must grant world read access.

> The request-library-file-spec parameter cannot be a search list.

##

### Examples

#1
    REQUEST LIBRARY IS "ACMS$EXAMPLES:DEPART.RLB";

> In this example, the file name of the request library is DEPART.RLB. The file is in the directory associated with the logical name ACMS$EXAMPLES.

#2
    REQUEST LIBRARIES ARE
      "ACMS$EXAMPLES:DEPART.RLB" WITH NAME DEPARTREQ,
      "ACMS$EXAMPLES:PERSREQ.RLB" WITH NAME PERSREQ;

> When you name more than one request library for a task group, you must use the WITH NAME keywords to assign names to each library. Each task in the task group uses a library name to refer to the request library it uses. In this example, the unique names of the request libraries are DEPARTREQ and PERSREQ.

# REUSABLE Subclause (Server)

> Identifies a server process as able to process more than one processing step for more than one task without being restarted. Server processes that are not reusable must be started each time they are needed.

## Format

> [ NOT ] REUSABLE ;

## Clause Default

> The REUSABLE subclause is optional. DCL servers and procedure servers are reusable by default.

## Notes

> When a server is reusable, ACMS can delete the server process only when server context is released or at the end of a task instance. Except for servers with USERNAME OF TERMINAL USER, ACMS keeps the server process active for multiple processing steps. When a server is not reusable, ACMS deletes the server process at the end of each processing step.

> Only servers that are reusable can retain server context between processing steps of a task.

> If a server has the USERNAME OF TERMINAL USER subclause, that server cannot be used by more than one task instance, whether it is reusable or not. ACMS runs down the server when server context is released.

> Nonreusable procedure servers are designed for use where a step procedure opens channels to the task submitter's terminal, but does not close the channels before completing.

> You can use a nonreusable procedure server to avoid ACMS canceling the task when a step procedure does not close all open channels to a task submitter's terminal. For optimal performance, nonreusable procedure servers should include only step procedures that do not close all open channels to a task submitter's terminal.

> Nonreusable procedure servers cannot participate in distributed transactions. ADU does not build the task group, if a task that starts or participates in a distributed transaction contains a procedure call to a procedure server defined with the NOT REUSABLE clause.

## Example

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

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

# RUNDOWN ON CANCEL Subclause (Server)

> Causes a procedure server to exit when a task cancel occurs while the task is keeping context in that server. When the server exits, ACMS releases server context.

## Format

## Clause Default

> The RUNDOWN ON CANCEL subclause is optional. The default characteristic is RUNDOWN ON CANCEL.

## Notes

> If you use the RUNDOWN ON CANCEL subclause and a task instance has active server context when the task is canceled, ACMS releases that context and stops that server process.

> If you specify the RUNDOWN ON CANCEL IF INTERRUPTED subclause, ACMS runs down the server process only if ACMS interrupts the execution of a step procedure due to an exception. For example, ACMS does not run down the server process if the task was simply retaining server context. Use the RUNDOWN ON CANCEL IF INTERRUPTED subclause to avoid unnecessary process deletions and creations.

> When you use the NO RUNDOWN ON CANCEL subclause, ACMS does not release context or exit the server image. This can provide you with performance gains.

> If you use the NO RUNDOWN ON CANCEL subclause, you must make sure that active recovery units are ended and all locks are released when the task is canceled. You can use a cancel procedure to release locks.

> Use the NO RUNDOWN ON CANCEL subclause only when defining a procedure server.

## Example

    SERVER IS
          VR_READ_SERVER:
            PROCEDURE SERVER IMAGE IS "AVERTZ_DEFAULT:VR_READ_SERVER.EXE";
            INITIALIZATION PROCEDURE IS VR_READ_INIT;
            TERMINATION PROCEDURE IS VR_TERM;
            ALWAYS EXECUTE TERMINATION PROCEDURE ON RUNDOWN;
            RUNDOWN ON CANCEL IF INTERRUPTED;
            PROCEDURE ARE
               VR_COMPUTE_BILL_PROC,
               VR_FIND_CU_PROC,
               VR_FIND_SI_PROC;
    END SERVER;

> In this example, ACMS runs down the VR_READ_SERVER process only if an exception occurs which forces ACMS to interrupt the execution of one of the step procedures.

# SERVERS Clause (Task Group)

> Defines the servers that handle the processing work for the tasks in a task group.

## Format

## Parameters

> ### server-name

> A 1- to 31-character unique name. Use this name to refer to the server from other clauses in the task group definition and from the application definition.

> ### server-subclause

> Defines the characteristics of a server. Section 4.3 explains each of these subclauses.

## Clause Default

> The SERVERS clause is required. You must name at least one server for each task group you define.

## Notes

> You can use the SERVERS ARE clause more than once in a single task group definition.

> You can define two types of servers: DCL servers and procedure servers. When you define a procedure server, you create an executable image file that contains subroutines you call from task processing steps.

> Use the SERVER subclauses to define DCL and procedure server attributes.

##

### Examples

#1
    SERVER IS
      PERSONNEL: DCL PROCESS;
                 FIXED USERNAME;
    END SERVER;

> The PERSONNEL server is a DCL server; it does the processing work for DCL commands or procedures, DATATRIEVE commands or procedures, or OpenVMS images. The user name assigned to the server is the user name under which the server starts.

#2
    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;

> DEPARTMENT_SERVER is a procedure server: it handles the work of processing steps that include calls to subroutines. The procedure server image is in the file DEPARTGRP.EXE, which is in the directory associated with the logical name ACMS$EXAMPLES. The entry points in this image of the procedures that run when the image is started and stopped are DEPART_STARTUP and DEPART_SHUTDOWN. In addition, the entry points in the procedure server image of the procedures handled by the DEPARTMENT_SERVER are:

> - REVIEW_HISTORY_GET
> - REVIEW_SCHEDULE_GET
> - REVIEW_UPDATE_GET

# TASKS Clause (Task Group)

> Identifies the tasks belonging to the task group you are defining.

## Format

## Parameters

> ### task-name

> A unique name you create to identify a task. You can use as many as 31 characters to define a task name. You must assign a unique task name to each task you define in the task group.

> ### processing-subclause

> A subclause you use to define a task directly in a task group definition. You can define a task directly in a task group definition if that task:
> - Consists of a single unconditional processing step
> - Specifies no step actions
> - Specifies no default server or default request library
> - Uses no workspaces other than the ACMS system workspaces

> If a task definition does not follow these rules, name the task in the task group definition, but define it separately and refer to it by its CDD task path.

> A processing subclause describes the processing work for a task. The four processing subclauses are: CALL, CALL TASK, DATATRIEVE COMMAND, DCL COMMAND, and IMAGE. Section 4.2 explains these subclauses.

> ### task-path

> The CDD path name of a task definition. Use the task-path parameter to specify the location in the dictionary of task definitions not included in the task group definition. You must use the full CDD path name of each task unless you set your CDD default to the appropriate directory.

## Keywords

> ### [ NO ] DELAY

> Allows three seconds before ACMS clears the last screen of a task when that task ends. If you use the DELAY keyword, you cannot use the WAIT keyword in the same task definition. When you use the DELAY keyword, ACMS supplies it as a default value for the control definition of the task in the application. If you use the DELAY keyword, it must precede the processing subclause for the task.

> ### [ NO ] WAIT

> When a task ends, the WAIT keyword causes the terminal to display a message requesting the user to press `[Return]` when finished looking at the information on the screen. If you do not use the WAIT keyword, ACMS returns the user to the menu when a task ends. When you use the WAIT keyword, you cannot use the DELAY keyword in the same task definition. If you use the WAIT keyword, it must precede the processing subclause for the task.

> ### GLOBAL

> Specifies that a task can be selected from a menu, can be called by an agent, or can be called by another task. GLOBAL is the default task attribute.

> ### LOCAL

> Specifies that a task can be called only by another task.

> ### CANCELABLE

> Specifies whether or not a task can be canceled by a task submitter.

## Clause Default

> The TASKS clause is required. You must name at least one task for each task group you define.

## Notes

> Every task must have a unique name.

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

> If a task contains a block step, you cannot include the definition for that task in the task group definition.

> You can, in a single task group definition, name tasks whose definitions are included in the task group definition, as well as tasks that are defined separately and referenced by the task group definition.

> If you do not use the IN SERVER keywords with a processing subclause, ACMS uses the last server named in the immediately preceding SERVERS clause.

> If you use neither the DELAY nor the WAIT keywords, ACMS returns the user to the menu when the task ends, unless the application definition specifies WAIT or DELAY for the task.

##

### Examples

#1
    TASKS ARE
      EDITOR: DELAY;
              PROCESSING IS DCL COMMAND IS "$EDIT/TPU 'P1'"
                IN PRIVATE_UTILITY_SERVER;
      MAIL  : PROCESSING IS
                DCL COMMAND IS "$MAIL"
                 IN PRIVATE_UTILITY_SERVER;
    END TASKS;

> The two tasks named by this TASKS clause are: EDITOR and MAIL. The EDITOR task executes the DCL command EDIT/TPU, using a parameter the user supplies as a selection string. The server PRIVATE_UTILITY_SERVER handles this processing work. Because the task definition includes a DELAY clause, ACMS waits three seconds before clearing the last screen of the task and returning the user to a menu.

> The MAIL task executes the DCL command MAIL within the DCL server PRIVATE_UTILITY_SERVER.

#2
    TASKS ARE
      NEW_EMPLOYEE: TASK DEFINITION IS NEW_EMPLOYEE_TASK;
      CHANGE_PROFILE: TASK DEFINITION IS CHANGE_PROFILE_TASK;
    END TASKS;

> In this example, the TASKS clause names the tasks NEW_EMPLOYEE and CHANGE_PROFILE associated with a task group. Both these tasks have task definitions stored in the dictionary. In this example, the default directory is DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES. Therefore, you need use only the given names of the task definitions, rather than their full CDD path names.

Previous | Next | Contents | Index