Digital

NAME

PROCESSING PROCEDURE − An entry point in a processing server
 

DESCRIPTION

 
A processing procedure is a named program that you write, consisting of serial processing operations defined using standard COBOL or C. A processing procedure is called directly by a task, as defined by the task definition. Processing procedures must be local (within the same TPsystem) to the task invoking them.
 
A processing procedure typically performs computations, database access, or file operations for tasks and comprises:

oTop-level processing procedures whose interfaces are defined within a single processing group using a processing group specification

oNested processing procedures called by top-level processing procedures or other nested processing procedures whose interfaces are defined using standard COBOL or C. 

 
A task calls a top-level processing procedure in a processing group. The called procedure calls another (nested) procedure. Both procedures access resources.
 
This topic describes the relationship of processing procedures to STDL. STDL access and context rules differ depending on whether the processing procedure is top-level or nested and whether the transactional semantics of the processing server are multiple resource, single resource, or no resource.
 

Processing Procedure Transactional Semantics

 
You determine the transactional semantics of processing procedures when you compile the processing group. You specify which transaction model that the processing server supports.

       •Multiple resource
 
If the processing server is multiple resource (the default), a top-level processing procedure and the nested procedures that it calls execute within the context of the transaction started by the calling task.

       •Single resource
 
If the single resource transaction model is used, a top- level processing procedure can control a single resource transaction.

       •No resource
 
If the no resource transaction model is used, the ACMSxp processing server is built with no resource controls, because a top-level processing procedure can control its own transaction.

 
Processing procedures cannot send data to a display or accept data from a display. The results of a processing procedure calling itself, either directly or indirectly, are undefined.
 

Multiple Resource Transaction Model

 
In the transaction model, multiple resource top-level processing procedures and nested procedures execute within the context of a single transaction started by a task execution. In this transaction model, top-level processing procedures can:

       •Perform computations

       •Perform data manipulation

       •Access both transactional and nontransactional files

       •Access SQL tables

       •Transfer files

       •Raise exceptions (top-level processing procedures only)

       •Call a nested processing procedure. 
  C processing procedures can call only C nested processing procedures.
 
COBOL processing procedures can call either COBOL or C nested processing procedures.

       •Access workspaces when passed to a top-level processing procedure as arguments through a CALL PROCEDURE. 

       •Access context created by a previously executed top-level processing or nested processing procedure, if the processing procedure or the processing procedure that invoked the nested processing procedure follow the rules for processing group context. 

       •Create context to be accessed by a subsequently executed top-level or nested processing procedure, if the processing procedure or the processing procedure that invoked the nested processing procedure follow the rules for processing group context. 

       •Call a task. 

       •Handle exceptions. 

 
See the processing_group man page for details about processing group context. 
 

Single Resource Transaction Model

 
In the single resource transaction model, a top-level processing procedure provides calls to start, commit, and roll back a transaction that accesses a single transactional resource. The processing procedure must use routines with the following names:
 
  stdl_start_transaction
  stdl_commit_transaction
  stdl_rollback_transaction
 
All the procedure calls within processing procedures are composable. The processing processing procedures cannot call composable tasks.
 

No Resource Transaction Model

 
If you build the processing group with the no resource model, the processing server retains no context. Its processing procedures execute transactionally and assume all transaction control. Although all transaction control is in a processing procedure, the calling task must use a transaction block and therefore must be noncomposable.
 
Every call the processing procedure makes is noncomposable. The processing procedure can start, commit, and roll back a transaction using as many resources as it needs.
 

Execution Flow for Processing Procedures

 
A top-level processing procedure receives control when a task executes a CALL PROCEDURE statement. A top-level processing procedure:

       •Receives the initial input, if any, through the contents of workspaces passed as arguments on the call. 

       •Returns the results of the call. The normal execution flow returns output arguments through the workspaces passed as arguments on the call. If the top-level processing procedure returns an exception to the task, the output arguments are no longer valid. 

 
A nested processing procedure receives control from the top-level processing procedure or from another nested processing procedure when the processing procedure executes a procedure call. A nested processing procedure:

       •Receives the initial input, if any, through the contents of the arguments passed on the procedure call. 

       •Returns the results of the procedure call. The normal execution flow returns the arguments to the calling processing procedure. All errors in the execution of a nested procedure are returned to the calling processing procedure as specified in the COBOL or C standard. 
 

Arguments for Top-level Processing Procedures

 
The number, order, and type of arguments defined in the top-level processing procedure must match the number, order, and type of arguments for that processing procedure in the processing group specification.
 
The top-level processing procedure arguments have the following semantics:

       •The arguments are either passed by reference or passed using copy-in, copy-out semantics. 

       •The argument passes from the calling task to the called processing procedure, if the argument within the processing group specification specifies INPUT. If an argument passes as INPUT, the processing procedure must not write to the argument. If the processing procedure writes to the argument, the results are no longer valid. 

       •The argument passes from the called processing procedure to the calling task, if the argument within the processing group specification passes as OUTPUT. 

       •If INOUT is specified on the argument within the processing group specification, the argument obeys the semantics of both INPUT and OUTPUT. 

       •The initial value of workspaces passed as OUTPUT is undefined. 
 

Arguments for Nested Processing Procedures

 
The mechanism used to pass arguments between processing procedures written using the same programming language is specified by the programming language standard.
 
The mechanism to pass arguments between a procedure written using COBOL and a procedure written using C or to pass arguments between a procedure written using C and a procedure written using COBOL is undefined. However, the STDL data types must be mappable and transferable to and from C and COBOL data types.
 

Processing Group Context

 
Two processing procedure executions can share the same processing group context if all the following conditions are met:

       •Both executions are in the same transaction. 

       •Both executions are caused by calls from tasks sharing the same task group context. These are calls to top- level processing procedures and nested calls to nested processing procedures. 

       •The two top-level processing procedures involved in these executions are in the same processing group. 

       •Both executions are on the same TP system. 

       •Both procedures use the same programming language. 

 
Processing group context consists of:

       •File context

       •SQL context
 

File Context

 
File context is associated with a file descriptor and consists of:

       •File position indicator
 
Specifies the next record to be accessed within a given file during certain input and output operations. The setting of the file position indicator is affected by file operations as defined in COBOL and C.

       •For transactional relative and indexed files accessed with dynamic or random mode, access to the current value of any file record previously read, modified, or written in this transaction.  See the GROUP FILE SPECIFICATION topic in ACMSxp STDL Encyclopedia for the syntax to establish transactional file access. 
 
 

       •For nontransactional relative and indexed files accessed with dynamic or random mode and stream files, access to any data in the file. 

       •For C-ISAM files, access to file descriptors. 
 

SQL Context

 
SQL context is associated with SQL functions and consists of:

       •Cursors
 
ACMSxp software supports cursor sharing within a given transaction for multiple calls to the same top-level processing procedure and nested processing procedures called by processing procedures from the same task.

       •Access to previously modified SQL data within the current transaction

       •Access to previously read SQL data within the current transaction

 
External variables cannot be shared among processing procedures.
 

Context Access and Modification

 
Processing procedures have access to both file context and SQL context. A processing procedure can modify the existing context only by performing:
 
  File operations
  SQL operations
 
Establishment of file context depends on the type of file. On the first access to an indexed or sequential file, file context is undefined. On the first access to a sequential file within the current transaction, the processing procedure can rely on the following file context:

       •If the file is opened for INPUT or OUTPUT, the file position is at the beginning of the file. 

       •If the file is opened for EXTEND, the file position is at the end of the file. 

 
On the first access to a stream file within the current transaction, the processing procedure can rely on the following file context:

       •If the file is opened for READ, the file position is at the beginning of the file. 

       •If the file is opened for APPEND, the file position is at the end of the file. 

 
The processing group context is maintained until the transaction in which the context is created completes (commits or rolls back).
 

File Access and SQL Access

 
All relative and sequential file access must be done through COBOL processing procedures. Standard COBOL statements are used to read, write, and update records in relative and sequential files.
 
Access to indexed files must be done through COBOL or C processing procedures. Standard COBOL statements are used to read, write, and update records in indexed files. Standard ISAM functions are used in C to read, write, and update records in indexed files.
 
All stream file access must be done through C processing procedures. Standard C functions are used to read, write, and update streams of data in stream files.
 
Except for the following types of file, ACMSxp software opens all files by using a group file specification:

       •Nontransactional sequential files, which can be opened and closed using standard COBOL

       •Nontransactional stream files, which can be opened and closed using standard C

 
ACMSxp software must open the files prior to the first file access by a processing procedure. A processing procedure accesses a file using a file descriptor.
 
Processing procedures can use embedded SQL statements, including explicit cursor control, to access a collection of data. The first SQL statement in the processing procedure causes the SQL environment to be implicitly associated with the processing group. When the transaction completes (commits or rolls back), all context maintained in SQL for the procedure group for that transaction is no longer valid.
 
In a processing server built with the multiple resource transaction model, you cannot commit or roll back transactions in files or SQL. In a multiple resource processing group, all transaction demarcation must be left to the task definition. The following SQL operations are not allowed in the processing procedure of a multiple resource processing group:
 
  SQL COMMIT and ROLLBACK statements
  Diagnostics management
  Connection management
  Session management
  Dynamic SQL
  Schema definition and manipulation
 

File Transfer

 
Standard XFTAM functions can be performed from processing procedures on files previously opened and closed by C or COBOL procedures. Both the source and target files must be of the same file type.
 

Error Handling

 
If ACMSxp software fails to open files for a processing group, the processing procedures in the group are disabled.
 
All errors in the execution of a file operation in COBOL and C that do not stop the transaction from completing are returned to the processing procedure, as specified in the COBOL or C standard.
 
All errors in the execution of SQL statements that do not stop the transaction from completing are returned to the processing procedure, as specified in the SQL standard.
 
All errors in the execution of a nested processing procedure are returned to the calling processing procedure, as specified in the COBOL or C standard.
 
All nontransaction errors in the execution of a task called by a processing procedure are returned to the procedure. Transaction errors are returned to the task that called the top-level processing procedure that caused the task to be invoked.
 
All errors in the execution of a file operation or SQL statements that stop the transaction from completing are returned to the processing procedure, as specified in the SQL standard. The processing procedure should raise a transaction exception to be returned to the calling task.
 
A top-level processing procedure generates an exception by setting fields in an external variable. Use the variable to set:
 
  Exception code
  Exception class
 
A top-level processing procedure generates transaction and nontransaction exceptions by setting either the exception code or class.
 
If a top-level processing procedure generates an exception, the output arguments of the procedure are no longer valid in the task context.
 

Calling a Task

 
A processing procedure can call a composable or noncomposable task. The processing procedure uses a client stub procedure to call a task. To share transaction context, sequential calls from one task to another task must be performed with WITH DEPENDENT WORK.
 

RELATED INFORMATION

Syntax: call_procedure(1), exception(1), processing_group(1), task_definition(1)

acmsxp_introduction(1)