| Previous | Contents | Index |
This chapter discusses the following topics:
This chapter also provides reference material in alphabetical order for calling SI services in agent programs.
Before an agent program can call any ACMS tasks, it must identify one or more task submitters to ACMS. The SI provides a service to sign the task submitter in to ACMS.
After the ACMS Central Controller (ACC) checks the identity of the task submitter, the agent program must indicate the types of exchange I/O to be performed. The SI provides a service that allows the agent program to declare the types of exchange I/O to be performed, setting up the necessary data structures to support the I/O methods selected. If TDMS exchange I/O is declared, the SI services open a TDMS channel.
When the submitter is finished performing exchange I/O, an agent program calls an SI service to finish any I/O that has been initialized, and frees any resources used by the task submitter.
After exchange I/O is terminated and the resources are freed, the agent program can then sign out one or more task submitters. The SI provides services to sign the task submitter out of ACMS. Figure 4-1 shows how an agent program interacts with ACMS components to sign a task submitter in to ACMS.
Figure 4-1 Signing In a Task Submitter to ACMS
The ACC verifies the user name and device name against the ACMSUDF.DAT user definition file, the ACMSDDF.DAT device definition file, and the SYSUAF.DAT file.
Table 4-1 shows the SI initialization services.
| Service Name | Description |
|---|---|
| ACMS$SIGN_IN | Identifies a task submitter to ACMS and returns a SUBMITTER_ID. |
| ACMS$SIGN_OUT | Removes a task submitter from ACMS. |
Only users authorized with the ACMS User Definition Utility (UDU) can gain access to ACMS. Also, if the task uses a terminal or other device for I/O, the terminal or device must be authorized with the ACMS Device Definition Utility (DDU). See Compaq ACMS for OpenVMS Managing Applications for more information about authorizing users and devices with UDU and DDU.
Table 4-2 shows the SI exchange I/O services. You must use these services for any task that uses DECforms (FORM I/O).
| Service Name | Description |
|---|---|
| ACMS$INIT_EXCHANGE_IO | Readies the agent program to perform various types of exchange I/O. Specifies the type of I/O to be performed and returns an exchange I/O ID. |
| ACMS$TERM_EXCHANGE_IO | Cleans up after the agent program is finished performing exchange I/O for tasks. Allows an agent program to finish any I/O initialized by the ACMS$INIT_EXCHANGE_IO services, freeing any resources being used by the submitter. |
The exchange I/O services and reference material for calling them in
agent programs are discussed in Section 4.3 and Section 4.4.
4.1 Authorizing an Agent Program in ACMS
An agent program can submit tasks under its own OpenVMS user name or under other user names:
UDU> ADD user-name/AGENT |
ACMS assumes that privileged agent programs verify their task submitters and any devices they use. For example, an agent program might verify a terminal user by asking for a name and password and checking them against a database maintained by the agent program.
If the agent program submits tasks that use terminal I/O, the agent program must pass the terminal's device name to ACMS when it signs in the task submitter. Unless the agent program has been authorized with the OpenVMS SHARE privilege, ACMS also checks that the agent program owns the terminal.
If the agent program submits tasks that do no I/O or that do stream
I/O, the agent program can either omit the device name parameter or
pass the value NL: for the device name. If the agent program omits the
device name, it defaults to NL:.
4.2 Signing In a Task Submitter to ACMS
An agent program uses the ACMS$SIGN_IN service to identify a task submitter's user name and device name (if I/O is to be performed on a terminal) to ACMS during sign-in. After ACMS verifies the user name and device, the agent program can submit tasks to ACMS.
The ACMS$SIGN_IN service assigns a submitter ID, which is passed to other SI services that the agent program calls for this task submitter. The sign-in service also provides an optional cancel routine that notifies the agent program if the submitter ID is forced out of the ACMS system because the system stopped or because an operator canceled the submitter.
If an agent program attempts to sign a user in to ACMS when the ACMS system is not started, two results can occur:
ACMS$_NOSYSTEM, The ACMS system was not available |
ACMS$_SIGNIN_NOAUTH, Sign in completed successfully without authentication. |
The following pseudocode shows how an agent program can handle both situations:
Signin_status = ACMS$SIGN_IN
if signin_status eql ACMS$_SIGNIN_NOAUTH
then
sign_out the submitter
if signin_status eql ACMS$_SIGNIN_NOAUTH or ACMS$_NOSYSTEM
then
[exit the agent
or
retry "n" times]
|
An agent program must sign a user in to ACMS with a "username" argument to ACMS$SIGN_IN in capital letters. |
If a user-generated character string descriptor is used, the length field of the string must be exactly the same as the length of the character string that describes the user name. If either of these conditions is not met, the ACMS$SIGN_IN service returns the following message:
ACMS$_BADUSER - The user is either not in the user definition
file or not in SYSUAF.
|
The agent program calls ACMS$INIT_EXCHANGE_IO to specify the type of I/O to be performed. The service returns an exchange I/O ID. This ID keeps track of the types of I/O the submitter can perform. The exchange I/O ID is passed to the call or start call service as the third argument in the task argument list.
You must supply the exchange I/O parameter. This value is returned upon successful completion of the call.
Exchange I/O for a task is performed by either the application execution controller or the ACMS code running in the agent program. Exchange I/O takes place in the agent process for:
The Application Execution Controller (EXC) performs exchange I/O for local TDMS tasks only.
To perform terminal I/O from a DCL or a procedure server, call
ACMS$INIT_EXCHANGE_IO. ACMS$SIGN_IN provides the device name. That
device name is passed to the DCL or procedure server.
4.4 Terminating Exchange I/O
The ACMS$TERM_EXCHANGE_IO service allows an agent program to finish any
I/O initialized with ACMS$INIT_EXCHANGE_IO. ACMS$TERM_EXCHANGE_IO frees
any resources being used by the submitter. For example, DECforms
sessions or TDMS channels are freed by ACMS$TERM_EXCHANGE_IO.
4.5 Signing Out a Task Submitter from ACMS
The agent program uses the ACMS$SIGN_OUT service to remove a task submitter from ACMS. The sign-out service identifies the task submitter by its submitter ID. The sign-out service provides an optional parameter to cancel all calls still active when the sign-out service executes. If this parameter is omitted and calls are still active, the sign-out service fails and returns a status code to the agent program indicating there are still active calls for this submitter.
The rest of this chapter contains reference material for using ACMS$INIT_EXCHANGE_IO, ACMS$SIGN_IN, ACMS$SIGN_OUT, and ACMS$TERM_EXCHANGE_IO in an agent program.
4.6 ACMS$INIT_EXCHANGE_IO
Specifies the type of I/O the agent program or device can perform.
ACMS$INIT_EXCHANGE_IO is called by the agent program and returns an
exchange I/O ID.
For submitters that enable TDMS, a call to ACMS$INIT_EXCHANGE_IO opens a TDMS channel.
If an agent program enables stream I/O and associates it with a submitter, the agent program must call ACMS$WAIT_FOR_STREAM_IO for all tasks (except tasks that do no terminal I/O), whether or not the task performs stream I/O. |
ACMS$INIT_EXCHANGE_IO
(submitter_id.rq.r,
exchange_io_id.wq.r,
[io_enable_flags.rl.r],
[item_list.rx.r],
[io_capabilities_flags.wl.r])ACMS$INIT_EXCHANGE_IO_A
_id.rq.r,
_io_id.wq.r,
[io_enable_flags.rl.r],
[item_list.rx.r],
[io_capabilities_flags.wl.r],
[comp_status.wq.r],
[efn.rbu.r],
[astadr.szem.r],
[astprm.rz.v])
submitter_id
The submitter ID corresponding to a signed-in submitter (user). This ID is returned by the ACMS$SIGN_IN service. No default submitter ID is allowed.exchange_io_id
This ID keeps track of the type of I/O the submitter is performing. This ID is passed to the call or start call service as the third argument in the task argument list.The exchange_io_id parameter must be supplied. This value is returned upon successful completion of the call.
io_enable_flags
These flags indicate which type of I/O the agent program wishes to perform. If this flag is not supplied, the agent program can call a task that performs DECforms and TDMS I/O, but it cannot use the Request Interface.To use TDMS, the default value of the io_enable_flags argument initializes the agent program. If it is certain that tasks will never use TDMS I/O, disable TDMS to conserve resources. If the ACMS$V_IO_DISABLE_TDMS flag is set on the call to ACMS$INIT_EXCHANGE_IO, TDMS is disabled for the agent process. Because TDMS is completely disabled in the agent process, if a task that uses TDMS for I/O is selected, it is canceled.
To use DECforms, the default value of the io_enable_flags argument initializes the agent program. If you are certain that you will never use DECforms, it is advisable to disable DECforms in order to conserve resources. If the ACMS$V_IO_DISABLE_DECFORMS flag is set on the call to ACMS$INIT_EXCHANGE_IO, DECforms is disabled for the agent process. Because DECforms is completely disabled in the agent process, if a task that uses DECforms for I/O is selected, it is canceled.
To use the Request Interface (RI), you must set the ACMS$V_IO_ENABLE_SYNC_RI flag on the call to ACMS$INIT_EXCHANGE_IO. In some cases, it may be desirable to disable DECforms and TDMS. For example, if the device is not supported by DECforms or TDMS, disabling DECforms and TDMS can conserve resources. Further information regarding the RI is in Compaq ACMS for OpenVMS Writing Applications.
Stream I/O is implicitly enabled by passing a connect ID in the item list.
item_list
This is the address of an item list describing the information requested. An item list is an OpenVMS data type that is used to pass information to and from a service. Item lists are made up of one or more item descriptors. The list of item descriptors must be terminated by an item code of 0. Detailed information regarding item lists is in OpenVMS Programming Interfaces: Calling a System Routine.Possible item codes are:
- ACMS$K_TDMS_CHANNEL
To obtain TDMS channel codes, set up an item list with an entry whose item code is ACMS$K_TDMS_CHANNEL. The buffer is a longword that receives the channel number.- ACMS$K_CONNECT_ID
If you wish to use stream I/O in the agent program, you need to provide an entry in the item list. The buffer is a quadword that receives the connect ID. The connect ID returned by the service is used to wait for and reply to stream I/O operations. See Chapter 6 for further details regarding stream I/O.io_capabilities_flags
This flag is a longword containing bits indicating which I/O methods are successfully initialized. The following bits are defined:
- ACMS$V_DECFORMS_AVAILABLE
This bit is set if DECforms is successfully initialized. If DECforms is not installed on the system, or was disabled, the bit is clear.- ACMS$V_TDMS_AVAILABLE
This bit is set if TDMS is successfully initialized. If TDMS is not installed on the system, or was disabled, the bit is clear.
- ACMS$V_STREAM_AVAILABLE
This bit is set if the stream services are successfully initialized.- ACMS$V_RI_AVAILABLE
This bit is set if ACMS has successfully enabled the RI.
The parameters comp_status.wq.r, efn.rbu.r, astadr.szem.r, and astprm.rz.v are asynchronous service arguments. See Chapter 2 for a discussion of these parameters.
The following list summarizes each error returned by ACMS$INIT_EXCHANGE_IO.The return status codes indicating success or failure of the call follow:
Status Severity Level Description ACMS$_NORMAL Success Normal successful completion. ACMS$_SOME_IO_NOT_AVAILABLE Success Some of the requested I/O methods have not been initialized. ACMS$_PENDING Informational Successful operation pending asynchronous completion. The final status is in the completion status block. ACMS$_USERMODE Error The user mode was invalid. ACMS$_INVSUB Error The submitter ID was invalid. ACMS$_NTSNIN Error The submitter was not signed in. ACMS$_INVEXCHIOID Error The exchange I/O ID was invalid. ACMS$_INVDEV Error The device name was invalid. ACMS$_INVFLAGS Error Invalid flags word. ACMS$_INVENBRI Error Invalid ENABLE RI flags. ACMS$_INVITEMDESC Error Invalid item list. ACMS$_INVITEMCODE Error Invalid item code. ACMS$_INVBUFSIZ Error Invalid buffer size. ACMS$_INVBUFADR Error Invalid buffer address. ACMS$_INVRETLEN Error Invalid return length. ACMS$_INVIOCAPFLAG Error Invalid I/O capabilities flag. ACMS$_INVCMPSTS Error Invalid completion status. ACMS$_INVEFN Error Invalid event flag number. ACMS$_INVASTADR Error Invalid AST routine address. ACMS$_INV_SIGNOUT_ACTIVE Error Submitter is in process of sign-out. ACMS$_INTERNAL Error ACMS internal error.
ACMS$INIT_EXCHANGE_IO can also return invalid status messages associated with the following services, among others:
4.7 ACMS$SIGN_IN
Signs a task submitter in to ACMS.
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])
submitter_id
The submitter identification that is output by the ACMS$SIGN_IN service.username
The OpenVMS user name of the submitter signing in. The default is the agent program's user name. The ACMS Central Controller (ACC) makes sure that the user name exists in ACMSUDF.DAT. If the user name specified is different from the agent program's user name, ACC verifies that the agent program's user name is privileged by checking the agent program definition in the ACMSUDF.DAT database file.
Note
An agent program must sign a user in to ACMS with a capitalized "username" argument to ACMS$SIGN_IN.If a user-generated character string descriptor is used, the length field of the string must be exactly the same as the length of the character string that describes the user name.
device
The terminal device name that you supply if the task performs I/O to the terminal. The device name can be a physical device name or a logical name. The default is NL:. ACC makes sure that the device name exists in the ACMSDDU.DAT database file.cancel_routine
The routine called (at AST level) when the submitter is canceled. If this parameter is omitted, the agent program receives no notification when the submitter is canceled. Any further operations by this submitter fail. When this parameter is used, the agent program receives notification when the submitter is canceled, after which the following parameters are passed to the cancel routine:
- cancel_param
The cancel user parameter that was passed with ACMS$SIGN_IN. This is passed by value, rather than by reference.- submitter_id
The address of the two-longword identification of the submitter being canceled. This is the address of the submitter_id passed by ACMS$SIGN_IN.- reason
The longword indicating the reason for the user cancellation. The possible reasons are:
- ACMS$_ACMS_GONE---the ACMS system has stopped
- ACMS$_SUB_CANCELED---the submitter was canceled by an operator request
This is passed by value, rather than by reference.cancel_param
The value to be passed to the cancel routine.
The parameters comp_status.wq.r, efn.rbu.r, astadr.szem.r, and astprm.rz.v are asynchronous service arguments. See Chapter 2 for a discussion of these parameters.
The return status codes indicating the success or failure of the call are:
Status Severity Level Description ACMS$_NORMAL Success Normal successful completion ACMS$_PENDING Informational Successful operation pending asynchronous completion. The final status is in the completion status block. ACMS$_BADAGENT Error The agent is not a valid ACMS agent program. ACMS$_BADDEVICE Error The device is not defined in the device definition file. ACMS$_BADUSER Error The user is either not in the user definition file or not in SYSUAF. ACMS$_INSUFPRM Error Not enough arguments were passed to this service. ACMS$_INTERNAL Error Internal error. ACMS$_INVASTADR Error The AST address was invalid. ACMS$_INVCANAST Error The cancel user routine was invalid. ACMS$_INVCMPSTS Error The completion status block was invalid. ACMS$_INVDEV Error The device name was invalid. ACMS$_INVEFN Error The event flag was invalid. ACMS$_INVLOGIN Error Invalid login attempt. ACMS$_INVSUB Error The submitter ID was invalid. ACMS$_INVUSER Error The user name was invalid. ACMS$_NODEVACC Error No access to specified device. ACMS$_SYNASTLVL Error Synchronous services may not be called from AST level. ACMS$_USERMODE Error This service must be called from user mode.
| Previous | Next | Contents | Index |