presentation procedure(1) — Commands
Digital
NAME
PRESENTATION PROCEDURE − a callable program that accesses a display or other input/output devices
DESCRIPTION
A presentation operation provides access to a display and other input/output devices.
A presentation procedure is contained within a STDL presentation group. This topic describes the relationship of presentation procedures to STDL. For information about suggested or required programming practices for use with STDL applications, see the C PROGRAMMING or COBOL PROGRAMMING topics in ACMSxp STDL Encyclopedia.
Presentation Procedure Role
A presentation procedure handles the transfer of data between the STDL task and the application user display. If you use commercial presentation tools and the ACMSxp Desktop software for your client and presentation services, you can write presentation procedures with tools supported by ACMSxp Desktop software.
A CALL PRESENTATION statement in a task definition calls a presentation procedure to send data to a display, to get data from a display, or to do both. A presentation procedure executes independently of any transaction started by a task.
The types of exchanges that occur between the task and the display in a CALL PRESENTATION are:
oSend
Takes data from the task and displays it on a physical device. No arguments are returned to the task.
oReceive
Takes data from the physical device on which it is displayed and returns it to the task. No arguments are sent to the display.
oTransceive
Combines the semantics of a send exchange and a receive exchange. A transceive passes data in both directions.
Send Exchange
The SENDING in a CALL PRESENTATION performs a send exchange that runs a send presentation procedure; the procedure can:
oAccept data from a calling task. SENDING in the CALL PRESENTATION statement identifies the workspaces that the calling task sends.
oSend data to the display.
oStore data for access by a subsequently executed CALL PRESENTATION with the same presentation group for the same display, or access data stored by a CALL PRESENTATION previously executed within the same presentation group for the same display.
oAccess static data defined within the send presentation procedure.
oReturn any exception to the task.
The send exchange can also operate transactionally.
Transactional Send Exchange
A presentation procedure operating transactionally is not coded any differently than one that operates nontransactionally. The difference in the operation is in exception handling facilitated by the management environment on the TPsystem. In a transactional send exchange, exceptions do not return to the calling task, but are handled by the TPsystem.
The TPsystem that supports transactional send exchanges runs a recoverable send server that handles exceptions in the transactional send exchange. The server stores the send exchange data in a system queue, the send queue. If an exception makes the send exchange data undeliverable, the send queue retains the data.
The ACMSxp client or a user-written client program can call the interface in the recoverable send server to retrieve the undelivered transactional send data for a particular user. The procedure ACMS_SHOW_SEND_ERRORS supplied with the recoverable send server provides this retrieval. A client program can also retrieve all undelivered transactional send data for all users. The procedure ACMS_SHOW_ALL_SEND_ERRORS supplied with the recoverable send server provides this retrieval.
Both these procedures are provided in the ACMS_SEND_ERRORS interface of the recoverable send server (acms_rsend_svr). Use the following syntax to call either procedure.
{ ACMS_SHOW_SEND_ERRORS }
CALL TASK { ACMS_SHOW_ALL_SEND_ERRORS }
{ }
IN ACMS_SEND_ERRORS USING <workspace-name> ;
Use the name or names of the workspaces for the transactional send exchange data.
Receive Exchange
The RECEIVING in a CALL PRESENTATION performs a receive exchange that runs a receive presentation procedure; the procedure can:
oReturn data to a calling task. The RECEIVING clause in CALL PRESENTATION identifies the workspace or workspaces that the receive presentation procedure returns to the calling task.
oAccept data from the display.
oStore data for access by a subsequently executed CALL PRESENTATION with the same presentation group for the same display, or access data stored by a CALL PRESENTATION previously executed within the same presentation group for the same display.
oAccess static data defined within the receive presentation procedure.
oGenerate an exception.
Transceive Exchange
The SENDING and RECEIVING in a CALL PRESENTATION perform a transceive exchange that runs a transceive presentation procedure. This CALL PRESENTATION combines the semantics of a send and a receive exchange. The transceive presentation procedure can:
oAccept data from the calling task and return data to the calling task. SENDING in the CALL PRESENTATION identifies the accepted workspaces and RECEIVING in the CALL PRESENTATION identifies the returning workspaces.
oAccept data from the display and send data to the display.
oStore data for access by a subsequently executed CALL PRESENTATION with the same presentation group for the same display.
oAccess data stored by a CALL PRESENTATION previously executed within the same presentation group for the same display.
oAccess static data defined within the transceive presentation procedure.
oGenerate an exception.
Presentation Group Context
An executing presentation procedure creates a context that defines the processing of the presentation procedure. Presentation group context is the sharing of data between one execution of a presentation procedure and the subsequent execution of another presentation procedure.
If all of the following conditions are met, two CALL PRESENTATION executions can share the same presentation group context.
oBoth presentation procedures are in the same presentation group.
oBoth presentation procedures are called by the same task execution.
oBoth executions are on the same TP system.
Presentation group context consists of:
oStatic data
Static data is defined by the presentation procedure and cannot be modified by the user. Static data is often referred to as screen literals or background text.
oDynamic data
Dynamic data is obtained from the task and the display. Subsequent input operations from the display or additional data sent from the task can modify the dynamic data. Dynamic data is often referred to as screen data or form data.
Presentation group context is maintained until the end of the task execution.
Initialization Procedure
You can write an optional initialization presentation procedure to associate with each presentation group. The initialization procedure:
oEstablishes context required by a presentation procedure.
The presentation initialization procedure defined using the presentation group specification establishes initial context needed by the user-written presentation procedures.
The presentation initialization procedure is implicitly invoked for each display by the ACMSxp system before any presentation procedure within the specified presentation group is executed at the establishment of presentation group context.
The ACMSxp software passes the display name and the default language as text to the presentation initialization procedure.
The presentation initialization procedure returns a presentation group handle. The presentation group handle is an integer value that is passed to all presentation procedures executed on behalf of this display within the presentation group. Presentation procedures can use the presentation group handle to access context established by the presentation initialization procedure, or to store context to be used by another presentation procedure.
oHas the following arguments:
-Display-name (read-only, 255-character text)
Uses environment information to associate displays in an implementation-specific manner.
-Client-language (read-only, 255-character text)
Names the human language passed to the task on the task call.
-Presentation group handle (write-only, integer)
A user-generated identifier by which the procedures in the presentation group share context.
Termination Procedure
You can write an optional termination procedure to associate with each presentation group. The termination procedure:
oInvalidates the presentation group context established by the initialization procedure.
oReleases any resources allocated by the presentation procedure.
oHas this argument:
Presentation group handle (read-only, integer)
The termination procedure is invoked when the task execution completes. The ACMSxp system invokes the termination procedure at the abnormal termination of an exchange as the result of an exception or user cancellation.
RELATED INFORMATION
Syntax: call_presentation(1), exception(1), presentation_group(1), presentation_procedure(1), stdl_syntax(1), task_definition(1)