Digital

NAME

CALL PRESENTATION −  a statement in a task definition that invokes a procedure in a presentation server
 

SYNOPSIS

Send Exchange:
 
[<label-name>:] CALL PRESENTATION <presentation-procedure-name>
                   IN <presentation-group-name>
                   [ WITH [ NO ] TRANSACTIONAL WORK ]
                   SENDING [ <workspace-name> ] [ ,... ] ;
 
Receive Exchange:
 
[<label-name>:] CALL PRESENTATION <presentation-procedure-name>
                   IN <presentation-group-name>
                   [ WITH [ NO ] TRANSACTIONAL WORK ]
                   RECEIVING [ <workspace-name> ] [ ,... ] ;
 
Transceive Exchange:
 
[<label-name>:] CALL PRESENTATION <presentation-procedure-name>
                   IN <presentation-group-name>
                   [ WITH NO TRANSACTIONAL WORK ]
                   SENDING [ <workspace-name-1> ] [ ,... ]
                   RECEIVING [ <workspace-name-2> ] [ ,... ] ;
 
Broadcast Send Exchange:
 
[<label-name>:] CALL PRESENTATION <presentation-procedure-name>
                   IN <presentation-group-name>
                   WITH BROADCAST LIST <list-name> NO TRANSACTIONAL WORK
                   SENDING [ <workspace-name> ] [ ,... ] ;
 

PARAMETERS

       •label-name
 
An unqualified internal identifier associated with the statement, for use in flow control operations.

       •presentation-procedure-name
 
A qualified external identifier specifying the name of a presentation procedure in the presentation group specification in which the presentation procedure is defined, if a user-written presentation procedure is used. The presentation group specification that contains the corresponding presentation procedure must be available when you compile the presentation group specification.

       •presentation-group-name
 
An unqualified external identifier specifying the name of the presentation group in the presentation group specification defining the called presentation procedure, if a user-written presentation procedure is used. The presentation group name can have a maximum of 17 characters.

       •workspace-name
 
An unqualified identifier specifying the name of a private or shared structured area of memory used for data storage in a task. You must declare the workspace name in the workspace declaration of the task.
 
The workspace name of a private workspace must be unique within a task definition. The workspace name of a shared workspace must be unique within a task group specification. A workspace name cannot be used for both a private workspace and a shared workspace in the same task definition.
 
The contents of workspaces in the SENDING phrase are sent to the presentation procedure. The contents of workspaces in the RECEIVING phrase are received from the presentation procedure.

       •workspace-name-1
 
An unqualified identifier giving the name of the workspace being sent to the display. A transceive exchange sends the contents of workspace-name-1 to the presentation server and receives the contents of workspace-name2.

       •workspace-name-2
 
An unqualified identifier giving the name of the workspace being received from the display. A transceive exchange receives the contents of workspace-name2 from the presentation server.

       •list-name
 
An operating system name that uniquely identifies a file specifying one or more display names to which the presentation procedure directs output.

DESCRIPTION

If a CALL PRESENTATION statement is used in a noncomposable task, it must be inside a transaction block. 
 
A CALL PRESENTATION statement runs a presentation procedure to perform an exchange. A presentation procedure is the part of a task definition that performs interaction between a task and a display. Exchanges are supported through a user-written presentation service. You create a user- written presentation service through use of ACMSxp Desktop software or by writing C or COBOL presentation procedures and STDL presentation groups, and compiling and linking them into presentation servers.
 
An exchange can contain the following elements:

oSend exchange
 
A send exchange transfers data from the task to a presentation service accessed through ACMSxp Desktop services, or to a presentation procedure.
 

oReceive exchange
 
A receive exchange transfers data from a presentation service accessed through ACMSxp Desktop services, or from a presentation procedure, to the task.
 

oTransceive exchange
 
A transceive exchange combines the operations of a send exchange and a receive exchange.
 

oWITH [NO] TRANSACTIONAL WORK attribute
 
Specifies whether send exchange and receive exchange operations are transactional. The default for a nonrestartable task is WITH NO TRANSACTIONAL WORK. The default for a restartable task is WITH TRANSACTIONAL WORK.
 
If a receive exchange specifies WITH TRANSACTIONAL WORK, the CALL PRESENTATION statement must be the first statement in the transaction block.
 
Transceive exchanges cannot be transactional. A transceive exchange must either specify or default to WITH NO TRANSACTIONAL WORK.
 

oBROADCAST LIST
 
For a send exchange, specifies that the ACMSxp system asynchronously run the presentation procedure for each display in the broadcast list. A broadcast send is nontransactional.

If the task is composable, the CALL PRESENTATION must specify SENDING and WITH TRANSACTIONAL WORK. You cannot include a nontransactional send exchange in a composable task. 
 
The arguments that you specify in SENDING or RECEIVING of the CALL PRESENTATION statement must match the arguments in the PROCEDURE statements of the presentation group specification in number, order, data types for fields, and lengths of fields within workspaces.
 
A task sends data to and receives data from a single display in a sequence of one or more operations.
 
You can write a user-written client program so that no display is assigned to a task, or so that a task can execute in an environment in which no display is assignable to the task.
 

Send Exchange

The contents of the workspaces specified in the SENDING phrase are sent to the presentation procedure. 
 
The normal execution flow for a send exchange depends on the elements in the call.

     1.For a transactional send exchange, stores the workspaces in a transactional, durable storage and completes with default flow control. 

     2.For a nontransactional send exchange, executes the presentation procedure, providing the workspaces in the call, and completes with default flow control. 

Deviations from the normal execution flow occur when one of the conditions listed in the Exceptions section occurs. The call presentation completes with the exception. 
 
The execution of the presentation procedure completes before the next statement list executes.
 
For a send exchange specifying WITH BROADCAST LIST, after the CALL PRESENTATION executes, the ACMSxp software asynchronously executes a presentation procedure for each display in the broadcast list. If a display is unavailable, it is omitted from the list.
 

Transactional Send Exchange

 
You can design a send exchange to be transactional. A transactional send exchange guarantees that, if the transaction commits, the ACMSxp system safely stores the output data and attempts to send it to the presentation service for display, regardless of what happens after the transaction commits. The presentation procedure is executed after the transaction commits.
 
If none of the exceptions listed in the Exceptions section occurs, a transactional send exchange causes the workspaces to be placed in a transactional and durable store (a send queue) for delivery to the presentation service. By default, each TPsystem entity has a recoverable send server. At TPsystem startup, the recoverable send server creates a database to contain the transactional send data. If applications running under the TP system do not use transactional send exchanges, you can use system management directives to prevent the recoverable send server from starting. See ACMSxp Developing and Managing Applications for more information. 
 
If the transaction commits, the data is placed in the send queue database. The ACMSxp system executes transactional send exchanges sometime after the transaction commits, but before the next transaction begins. If there are no subsequent transactions, ACMSxp software executes the transactional send exchanges before the task ends. If the send exchange completes successfully, the data is deleted from the send queue database.
 
If the transaction rolls back, the presentation procedure is not executed and the data is discarded.
 
If a system error occurs before the transaction commits, ACMSxp software returns the system exception class and error message to the user. If a system failure occurs after the transaction commits, the data remains in the send queue database and the user does not see the send exchange data. The event is logged to the TP system event log. The data is deleted from the send queue database when:

oThe user or system manager retrieves the undelivered data from the transactional send. 
 

oA system management directive deletes the send queue element entity that represents the transactional send data. 

The transactional send exchanges of one transaction are delivered before the exchanges of any subsequent transaction. If multiple transactional send exchanges occur in the same transaction block, the data is delivered to the presentation service in the order that the send exchanges occurred, provided that all attempted deliveries succeed.  However, because a transactional send exchange executes after the transaction commits and a nontransactional send exchange executes within the transaction, ACMSxp cannot guarantee the order of exchanges if transactional and nontransactional send exchanges are mixed. 
 
See ACMSxp Developing and Managing Applications for information about design issues related to the order in which send exchanges are delivered to the presentation service. 
 

Retrieving Undelivered Data from a Transactional Send

 
The user or system manager can retrieve undelivered data from the send queue database by using a user-written client to invoke the following ACMSxp-supplied tasks in the ACMSxp-supplied task group:

oacms_show_send_errors is an ACMSxp task that retrieves undelivered exchange data intended only for the user prior to the system failure. 
 

oacms_show_all_send_errors is an ACMSxp task that allows the user to retrieve all the undelivered data in the send queue database. 
 
Specify ACMS_INTERFACE_PATH to the directory containing the task interface descriptor file before invoking the task.
 

oacms_send_errors is the ACMSxp task group specification that provides the interface for the two tasks; the interface descriptor file acms_send_errors_1_0.idf is located in the directory specified by ACMS_SYS_DIR. 

Invoke the tasks for display of undelivered transactional send exchange data as follows:

oFrom the ACMSxp client
 
Use the ACMSxp commands to invoke the transactional send errors tasks.
 

oFrom a user-written client
 
ACMSxp software supplies the client stub object acms_send_errors.o generated from the task group specification. Link the client stub with the user-written client program.
 
If the user-written client program uses a user-written presentation server, invoke the task by calling stub routines from the C or COBOL client program.

Receive Exchange

 
The contents of the workspaces specified in the RECEIVING phrase are received from the presentation procedure.
 
Normal execution flow for a transactional receive exchange is:

oIf a transaction has not restarted, executes the presentation procedure and stores the output of the presentation procedure. 
 

oIf a transaction has restarted, use the data stored on the first execution of the transaction. 
 

oComplete with default flow control. 

For a nontransactional receive exchange, executes the presentation procedure and completes with default flow control. 
 
Deviations from the normal execution flow occur when one of the conditions listed in the Exceptions section occurs. The call presentation completes with the exception and the values of the workspaces in the RECEIVING phrase are no longer valid.
 
You can design the first receive exchange in a transaction block to be transactional. Data from the first receive exchange can be saved and reused, if the transaction is restarted. The data is discarded when the transaction commits, or if the transaction is rolled backed with restart. However, the transactional receive exchange is not durable (it cannot survive a system crash), because the data is held in a buffer. A transactional receive exchange must be the first statement in the statement list of a transaction block.
 
You cannot include a receive exchange in a composable task.
 

Transceive Exchange

 
A transceive exchange executes the send exchange and the receive exchange and completes with default flow control. The CALL PRESENTATION must either specify or default to WITH NO TRANSACTIONAL WORK.
 
Deviations from the normal execution flow occur when one of the conditions listed in the Exceptions section occurs. The CALL PRESENTATION completes with the exception and the values of the workspaces in RECEIVING are no longer valid.
 
You cannot include a transceive exchange in a composable task.
 

EXCEPTIONS

The execution of a transactional send CALL PRESENTATION statement cannot generate exceptions. The TP system handles any exception, and an exception is not returned on the CALL PRESENTATION statement. 
 
CALL PRESENTATION statements other than transactional send exchanges can generate the exception classes described in the following sections. The sections describe the conditions leading to the exception class and can suggest actions to take.
 
You can program the CALL PRESENTATION to return any exception class.
 

AP-EXECUTION-FAULT

 
The AP-EXECUTION-FAULT exception class indicates one of the following error conditions:

oThe presentation procedure specified by the presentation procedure name in the CALL PRESENTATION (or in a nested procedure) contains an unhandled programming or logic error, such as an access violation or a divide-by-zero operation, or other unhandled programming or logic errors caused by the execution of the presentation procedure. 
 

oA display error occurs when the presentation procedure tries to access the display. 
 

oThe subscript used to refer to an element in a fixed-length array is invalid (referring to A(n) where n is less than one or n is greater than the maximum size of array). 
 

oThe subscript used to refer to an element in a variable-length array is invalid (referring to A(n) where n is less than one or n is greater than the value of the DEPENDING ON field). 
 

oThe value of the DEPENDING ON field used when referring to an element of a variable-length array is invalid (the value of the DEPENDING ON field is less than the minimum size of the array or the value of the DEPENDING ON field is greater than the maximum size of array). 
 

oThe value of the DEPENDING ON field was invalid when referring to a workspace name or workspace field containing a variable-length array. 

AP-INVOCATION-FAULT

 
The AP-INVOCATION-FAULT exception class indicates that a specification mismatch occurred on a CALL PRESENTATION. The interface for the called presentation procedure does not match the interface for a presentation procedure in the presentation group specification used when the calling task was compiled.
 

AP-RESPONSE-FAULT

 
The AP-RESPONSE-FAULT exception class indicates that the results of the CALL PRESENTATION could not be returned to the task that called the presentation procedure because of a syntax error.
 

ENV-EXECUTION-ERROR

 
The ENV-EXECUTION-ERROR exception class indicates that the presentation procedure executed by the send, receive, or transceive exchange could not complete due to a system failure on the TP system in which the task is executing.
 

ENV-INVOCATION-ERROR

 
The ENV-INVOCATION-ERROR exception class indicates one of the following error conditions:

oThe presentation group specified by the presentation group name in the CALL PRESENTATION is not available because of a system failure. 
 

oThe presentation procedure executed by the send exchange could not complete because the display is off line and not available. 

ENV-INVOCATION-FAULT

 
The ENV-INVOCATION-FAULT exception class indicates that either the presentation group specified by the presentation group name or the broadcast list in the CALL PRESENTATION is not defined within the TP system in which the task is executing.
 

REQUEST-TIMEOUT-ERROR

 
The REQUEST-TIMEOUT-ERROR exception class indicates that the time out limit (exchange timeout) for response from the presentation procedure is exceeded.
 

RELATED INFORMATION

Syntax: presentation_group(1), task_definition(1)

acmsxp_introduction(1)