HP OpenVMS Systems Documentation

Use the SERVERS clause to name the servers in a task group and to define the following:

• Server type
• Implementation characteristics of the server
• Default control characteristics of the server

Use server subclauses in the SERVERS clause to define each server you name.

If you define a server to be a DCL server, the only additional subclauses you can use to describe that server are the USERNAME subclause, the REUSABLE subclause, and the DYNAMIC USERNAME or FIXED USERNAME subclause. However, if you define a server to be a procedure server, you can use any of the clauses listed in Table 4-3 except DCL PROCESS.

You must use the END SERVERS keywords to signal the end of the servers you are defining within a SERVERS clause. Table 4-3 lists the server subclauses and gives a brief description of each.

Figure 4-3 shows the syntax for server subclauses in the SERVERS ARE clause.

Figure 4-3 Server Subclauses Syntax

Specifies that ACMS should always process the server's termination procedure when the server process is run down.

Format

ALWAYS EXECUTE TERMINATION PROCEDURE ON RUNDOWN;

Clause Default

The ALWAYS EXECUTE TERMINATION PROCEDURE subclause is optional. If you do not specify this subclause, ACMS does not process the server's termination procedure if the server process runs down because the task is canceled.

Notes

Use the ALWAYS EXECUTE TERMINATION PROCEDURE subclause only when defining a procedure server.

By default, ACMS processes a server's termination procedure when the server process is run down, unless the server process is being run down because the task was canceled. There might be times when you want to override this default by specifying the ALWAYS EXECUTE TERMINATION PROCEDURE subclause. For example, a server that uses global sections might need to clean up information in the global sections when the server process is run down.

Example

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

In this example, when DEPARTMENT_SERVER is run down, ACMS runs the DEPART_SHUTDOWN termination procedure, even if the server process is being run down because the task was canceled.

Names a procedure in a procedure server to do the work for a processing step.

Format

CALL PROCEDURE entry-point-name [IN server-name] [USING workspace-name [,...]];

Parameters

entry-point-name

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

server-name

The name of the server in which ACMS runs the procedure named by the CALL subclause. When you use the CALL subclause, the server you name must be a procedure 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.

workspace-name

The name of the workspace used by the procedure. You can name only the ACMS system workspaces when using the CALL subclause to define a task in a task group definition.

Clause Default

If you do not use a CALL subclause, ACMS does not call a procedure in a procedure server.

The CALL subclause is optional. If you are defining a task in a task group definition, you must include a CALL, DATATRIEVE COMMAND, DCL COMMAND, or IMAGE processing subclause within the TASKS clause.

The PROCEDURE command keyword is required if "task" or "procedure" is the procedure entry point name.

Note

Any procedure you name with the CALL subclause must run in a procedure server.

Examples

TASK IS
  ADDEMP: PROCESSING CALL PERSADD IN PERSONNEL_SERVER;
END TASK;
      

The ADDEMP task uses the PERSADD procedure in the PERSONNEL_SERVER.

CREATE GROUP PERSONNEL_GROUP
  MESSAGE FILE IS "SYS$SAMPLE:PERSMSG.EXE";
    FORM IS "SYS$SAMPLE:PERS_FORM" WITH NAME PERS_LABEL;
        SERVER IS
    PERSONNEL_SERVER:
      PROCEDURE SERVER IMAGE IS "PERSGRP.EXE";
      INITIALIZATION PROCEDURE IS PERS_START;
      TERMINATION PROCEDURE IS PERS_STOP;
      PROCEDURE IS PERSADD;
  END SERVER;
  TASK IS
    ADD_EMPLOYEE: PROCESSING CALL PERSADD;
  END TASK;
END DEFINITION;
      

This task group definition names one task, ADD_EMPLOYEE. The definition for the task contains a single processing step that calls the PERSADD procedure. The CALL subclause does not name the server in which the procedure runs. By default, ACMS uses the last server defined in the task group, PERSONNEL_SERVER.

Names a procedure that runs when a task instance is canceled while that task is executing a step procedure in the server or is maintaining server context in the server.

Format

CANCEL PROCEDURE IS cancel-entry-name ;

Parameter

cancel-entry-name

The entry point of the cancel procedure in the procedure server image. Do not enclose this name in quotation marks.

Clause Default

The CANCEL PROCEDURE subclause is optional. If you do not name a cancel procedure for a procedure server, ACMS does not run a cancel procedure for that server.

Notes

Use server cancel procedures to perform server process cleanup work to avoid having to run down a server process when a task is canceled while it retains context in the server. This cleanup work might include aborting a distributed transaction started by a step procedure; closing temporary files opened for a specific task instance; and closing terminal channels opened by a step procedure.

ACMS does not pass workspaces to server cancel procedures. Therefore, if you need information from workspaces to perform task cleanup work after a cancel, use the CANCEL ACTION phrase to call a step procedure.

Use the CANCEL PROCEDURE subclause only when defining a procedure server.

When a task instance is canceled while that task is executing a step procedure in a server or is maintaining context in a server, ACMS runs the cancel procedure named in the CANCEL PROCEDURE subclause of the server definition for any servers assigned to that task instance. ACMS then either frees up the server to be used by another task instance or runs down the server process.

Because a distributed transaction can be aborted at any time, a server cancel procedure can be called before or after a distributed transaction has been aborted. Therefore, server cancel procedures should not rely on the state of a distributed transaction.

If a server has a cancel procedure, ACMS uses the status returned by the cancel procedure to determine whether or not to run down the server process. Table 4-4 shows the actions ACMS takes for each return status.

Table 4-4 Server Process Rundown Actions

Return Status	Action taken by ACMS
ACMS$_RNDWN	Always run down server process.
ACMS$_RNDWNIFINT	Run down server process only if ACMS interrupts execution of a step procedure to cancel the task.
ACMS$_NRNDWN Other	Do not run down server process unless absolutely necessary. For example, if a step procedure leaves channels open to a terminal, or if a fatal exception, such as an access violation, occurs, ACMS runs down the server process.

The cancel procedure must be linked into the procedure server image with all other procedures required by the server.

Name the cancel procedure for a server in the CANCEL PROCEDURE subclause. If you use the cancel procedure as a step procedure, you must also specify the name of the procedure in the PROCEDURES subclause.

Example

SERVERS ARE
  PERSONNEL_SERVER: PROCEDURE IMAGE IS "PERSGRP.EXE";
                    PROCEDURE IS PERSADD;
                    CANCEL PROCEDURE PERSCANCEL;
  UTILITY_SERVER: DCL PROCESS;
                  DYNAMIC USERNAME;
END SERVERS;
      

PERSCANCEL is the name of the entry point of the cancel procedure in the PERSONNEL_SERVER procedure server image.

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 Guide to Using VMS Command Procedures.

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 Guide to Using VMS Command Procedures.

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.