| Previous | Contents | Index |
An agent program is a program that invokes a task that executes in an ACMS application. An agent process is an OpenVMS process in which an agent program executes. ACMS provides a default agent program called the command process (CP), which uses a forms interface to interact with the terminal user. The ACMS Systems Interface (SI) provides a set of services that allow programmers to write their own agent programs.
This chapter briefly describes SI services and tells how to call them
from an agent program.
1.1 The ACMS Systems Interface
The ACMS Systems Interface is a set of system services that you can use to enable user-written code in an agent process to submit ACMS tasks. The default ACMS command process (CP) is a supplied agent that handles user sign-in, menu presentation, task submission, and exchange steps with supported forms management systems such as DECforms.
By using the SI, you can write an agent program to replace or supplement the default ACMS task selection method. You can also write agent programs to meet special interfacing or user interaction requirements. Customer-written agent programs can coexist with the default agent programs supplied by ACMS.
Some examples of SI usage include:
Although you can access ACMS from an ALL-IN-1 agent, running the ALL-IN-1 system from within an ACMS DCL server process may have severe negative impact on system performance. |
This is only a partial list of all the extensions to ACMS that are possible using the SI. An agent program can be very simple or very complex; it can handle requests for a single user or multiple users.
An agent program designed to handle multiple users, however, is far
more complicated and involves developing asynchronous code. Before
attempting to implement any complex SI facilities, you must consider
the commitment of time and resources necessary to develop and support
an SI program.
1.2 Systems Interface Services
The SI provides a set of callable services to sign in, access tasks, and otherwise communicate with ACMS. Programmers must set up various data structures using a language that supports the OpenVMS calling standard.
Table 1-1 lists the groups of SI services and gives a brief description of each group.
Compaq ACMS for OpenVMS Writing Applications describes queuing and dequeuing services.
| SI Services | Description |
|---|---|
| Initialization Services | Provide a sign-in service to identify a task submitter to the ACMS system and a sign-out service to remove the task submitter from the ACMS system. |
| Exchange I/O Services | Specify the type of exchange I/O to be performed and terminate an agent program's exchange I/O. |
| Submitter Services | Submit tasks for processing by the ACMS run-time system. The submitter services are used to call and cancel tasks. |
| Stream Services | Implement alternate task I/O methods. The stream services are useful if you use asynchronous processing, simultaneous multitasking, or multithreaded agent programs. They are also useful when exchanging large amounts of data primarily in one direction on each exchange step, such as sending or receiving a list of data items. |
Detailed discussions of the four groups of SI services are in the following chapters:
In addition, two services, ACMS$SIGNAL and ACMS$WAIT, perform error
handling and synchronization functions common to many of the SI
services. A discussion and reference material for the ACMS$SIGNAL and
ACMS$WAIT services are included in Chapter 2.
1.3 Agent Programs
A task submitter is any authorized ACMS user who selects tasks for processing, provides input for that processing, and receives the results of that processing. Task submitters must also be authorized OpenVMS users.
An agent program uses the SI services on behalf of one or more task submitters. You can write an agent program in any language that supports the OpenVMS calling standard. A task submitter is associated with an OpenVMS user name that identifies the user to the ACMS system.
The function of the agent program is much like the ACMS command process. In fact, the ACMS command process is an agent program supplied with ACMS. An agent program can sign in to ACMS to represent a single task submitter or multiple task submitters, if necessary. An agent program interacts with the user or external system and invokes tasks to perform required processing. The method of interacting with a user can be a menu system on a terminal screen or some other method.
By default, a task submitter is a DECforms-supported terminal such as the DEC VT series terminals. However, an agent program can recognize almost anything as a task submitter---from a person sitting at a terminal to a badge reader, DECtalk, or a postage scale. Each of these external entities is supported by the agent program.
Figure 1-1 shows the steps agent programs use to submit tasks to the ACMS system.
Figure 1-1 Agent Programs Submitting Tasks to ACMS
Figure 1-1 shows the following:
This sequence of processing by an agent program is similar to that of
the ACMS command process. The primary work of the agent program is in
the third phase, where it calls ACMS tasks.
1.3.1 Calling Tasks
The main purpose of the SI is to allow access to an ACMS system from outside the typical ACMS environment. Agent programs do not have access to the standard ACMS menus and are, therefore, expected to provide their own methods of interacting with the user or external system. If menus are required, the agent program must support a menu system. In addition, the agent program is free to run any initial or final tasks, as required. Using the SI services, an agent program can also provide distributed processing functions such as communications between an ACMS system and other systems.
Agent programs can call tasks on behalf of one or more task submitters. Several agent programs can submit tasks at the same time; a single agent program can submit more than one task at a time on behalf of a submitter. These tasks can be selected in a combination of local node applications and remote node applications, as required. While the CP limits the interactive user to a single task initiated from the menu, you can write an agent program that allows the task submitter to access more than one task at a time.
An agent program can pass data to a task as arguments. A task can read and modify data stored in a task as argument workspaces. A task can also return the modified workspace contents to the agent program. The agent program can then use the data in subsequent task executions. See Chapter 5 for a discussion of the services you use to call ACMS tasks and to pass data as arguments.
An agent program can use the DECdtm services to start a distributed
transaction and then call a task as part of that transaction. When the
task completes, the agent program can commit the DECdtm transaction;
the agent program can thus coordinate the database I/O performed in the
agent with the I/O performed in the task.
1.3.2 Using Streams
Agent programs can call any ACMS task, including tasks that use form I/O, request I/O, or stream I/O. Explanations of these terms follow:
Streams are ACMS communication channels between an agent program and an application. Stream I/O can be used to interface other systems or devices not supported by form I/O and request I/O.
Streams provide communication between ACMS tasks and agent programs. Agent programs then communicate with devices not supported by DECforms or TDMS.
In many instances, you can use the Request Interface (RI) to communicate with unsupported devices (see Compaq ACMS for OpenVMS Writing Applications). Stream services currently offer advantages, however, in two situations:
Figure 1-2 shows the stream connection between an agent program and an ACMS Application Execution Controller (EXC).
Figure 1-2 Stream Connection
Because the agent program works on behalf of the task submitter, the
agent program creates and connects a stream between itself and the EXC.
The EXC is the interpreter of the task definition.
1.3.3 Using SI Identifiers
The SI uses a number of identifiers for communication between calls to the various services. The IDs used are:
Agent programs allocate memory for these structures and then pass the memory address to an SI service that either fills in the information or uses the information stored in the ID by a previous service.
Structure definitions for these IDs are currently available for BLISS, C, FORTRAN, MACRO, Pascal, and PL/I. Chapter 2 documents the definition and declaration files available for these languages. Other languages must define their own structures to store these IDs.
This chapter describes features common to the SI services and the
various languages that use them. The chapter also explains the
reference format used in the following chapters and describes the
ACMS$SIGNAL and ACMS$WAIT support services.
2.1 Features Common to the SI Services
All of the SI services follow the OpenVMS Calling and Condition
Handling Standards. This manual assumes you will use OpenVMS Programming Interfaces: Calling a System Routine and
the OpenVMS System Services Reference Manual as references for these standards when using the SI
services.
2.1.1 Service Call Specification
The following chapters contain reference information about the correct syntax and parameters for calling the SI services. The explanation of each service is divided into several parts:
| Name | Shows the service name in uppercase characters. |
| Description | Gives you a brief explanation of what the service does. |
| Format | Shows the syntax of the service. |
| Parameters | Explains the parameters you can use with the service. |
| Return Status | Lists each of the status values you can receive when you call the service and when the service completes. |
The format descriptions for the services use OpenVMS procedure parameter notation. Each parameter can have four characteristics, represented by two groups of symbols following the parameter. The characteristics definable for each parameter are:
<name>.<access type><data type>.<pass mech><parameter form>
The characteristics are always listed in the preceding order. A period (.) separates access and data types from the passing mechanism and the parameter form. For example:
comp_status.wq.r
In this example, comp_status is to be written by the service (w); comp_status is a quadword (q); and comp_status is passed by reference (r).
Table 2-1 defines the symbols used for parameter characteristics in format descriptions in this manual.
| Parameter Notation |
Symbol | Meaning |
|---|---|---|
| Access type | m | Modify access |
| r | Read access only | |
| s | Call without stack unwinding | |
| w | Write and read access | |
| Data type | bu | Byte logical (unsigned) |
| l | Longword integer (signed) | |
| lc | Longword return status | |
| lu | Longword logical (unsigned) | |
| o | Octaword integer (signed) | |
| q | Quadword integer (signed) | |
| t | Character-coded text string | |
| w | Word integer (signed) | |
| x | Data type by descriptor | |
| z | Unspecified | |
| zem | Procedure entry mask | |
| Passing mechanism | d | By descriptor |
| r | By reference | |
| v | By immediate value | |
| Parameter form | none | Scalar (also called atomic data type) |
| x | Class type by descriptor |
Each asynchronous SI service produces a status code when the service is
called and another when the service completes. The severity of these
status codes can be SUCCESS, INFORMATIONAL, WARNING, ERROR, or FATAL.
If the service returns a SUCCESS or INFORMATIONAL status code, the
completion events defined for the service occur. If the service returns
a WARNING, ERROR, or FATAL status code, the completion events do not
occur.
2.1.4 Synchronous and Asynchronous Calling Formats
SI services usually have two formats: a synchronous format and an asynchronous format. The exceptions are ACMS$SIGNAL and ACMS$WAIT, which have only a synchronous format.
Agent programs can call asynchronous SI services from either mainline or asynchronous system trap (AST) level. An agent program must call a synchronous service from mainline level; synchronous services return an error message if called from AST level.
The synchronous and asynchronous SI services perform all operations identically, except that the asynchronous services return a status message to the caller both when the initial call is made and when the completion events occur. Synchronous services return a status message to the caller only after the operation has completed.
When a call to a synchronous SI service returns to the calling routine, the service and all processing are finished. The service returns a completion status value to indicate the success or failure of the service. For example, an agent program might call ACMS$SIGN_IN to sign a task submitter in to the ACMS system. When control returns to the calling module, the agent program checks the return status to determine whether or not the sign-in service completed successfully.
Using the asynchronous version of the SI services allows an agent program to perform other processing work while the ACMS system is performing the processing associated with that service. The asynchronous services return a status code when the initial call is made to indicate whether or not ACMS accepted the request to perform that service. ACMS returns a success status to the calling agent program to indicate that ACMS is now processing the request. When the processing is complete, ACMS returns another status to the calling agent program to indicate whether or not the processing completed successfully.
Many of the services rely on asynchronous system traps (ASTs) being delivered in order to operate. Therefore, components that use these services should not disable ASTs for long periods of time. |
If it was unable to begin processing the request, ACMS returns a failure status when the initial call is made. For example, ACMS might return a failure status if it could not read an argument passed to the service. If a call to an asynchronous service fails and the service returns an error status to the calling agent program, the service does not take place, and ACMS does not set an event flag or call an AST completion routine.
The synchronous calling formats differ from the asynchronous calling formats in that they do not include the trailing _A at the end of the service name. The asynchronous SI services include four additional, optional arguments that handle asynchronous completion. Except for these four asynchronous service parameters, the parameter descriptions and return status messages discussed after the service formats pertain to both synchronous and asynchronous services. These four asynchronous service parameters are:
A description of each of these parameters follows:
comp_status
The final completion status of the service. This is a two longword block. The block is set to zero when the service starts successfully, and the return status message from the service is ACMS$_PENDING. When the service completes, the first longword of the block contains the final status. The completion status contains a nonzero value when the service is finished.efn
The event flag that is set when the service completes. When the service starts successfully and returns the ACMS$_PENDING status, the event flag is cleared. Because ACMS sets the event flag only when the service is done, the agent program should check the comp_status parameter first for a nonzero value to verify that the service really ended. See $SYNCH in OpenVMS System Services Reference Manual.astadr
The address of an AST routine to be called when the service completes. If the service started successfully (the return status is ACMS$_PENDING), this AST is delivered when the service completes.astprm
The parameter the AST passes to the service completion routine.
To determine the success or failure of a call to an asynchronous SI service, the agent program must supply the address of a quadword completion status block that ACMS can use to store the status result. An agent program normally uses an event flag or an AST completion routine to determine that an asynchronous service has completed. The agent program might also pass an optional parameter to the AST completion routine.
For example, the synchronous and asynchronous formats for ACMS$SIGN_IN are the following:
ACMS$SIGN_IN (submitter_id.wq.r,
[username.rt.dx],
[device.rt.dx],
[cancel_routine.zem.r],
[cancel_param.rz.v])ACMS$SIGN_IN_A (submitter_id.wq.r,
[username.rt.dx],
[device.rt.dx],
[cancel_routine.zem.r],
[cancel_param.rz.v],
[comp_status.wq.r],
[efn.rbu.r],
[astadr.szem.r],
[astprm.rz.v])
| Previous | Next | Contents | Index |