gtpd2m26Data Communications Services Reference

Application Programming Considerations

The design of application programs to run under control of a TPF system with the message routing facility must take into consideration system interfaces which are different from those presented by prior models of the TPF system. These considerations, as it will be explained in this section, influence the way application programs are written. System compatibility with existing applications is maintained as outlined elsewhere in this chapter.

Three major areas of system interface can be isolated at the application level:

  1. Input (to the application program).
  2. Use of support facilities.
  3. Output (from the application program).

This is described in TPF ACF/SNA Data Communications Reference for applications communicating with SNA logical units. However, the following is conceptually correct for all non-SNA terminals or SNA terminals utilizing a pseudo LNIATA address in a TPF system.

Input Interface To Application Programs

As already described in prior topics of the chapter, the message router or communication source program ultimately invokes an application input message editor as specified in the RCAT. When the application input message editor is given control for the textual interpretation of the data, the following standard interface is presented:

It should be noted that the RCPL should be preserved by the application for it is needed in order to transmit data (that is, reply to the input message). Since the system interface for data transmission is the ROUTC macro, it is not necessary to keep the RCPL in the work area of the ECB. In fact, a parameter of the ROUTC macro identifies the name of the system register containing a pointer to the storage location where the RCPL is to be found.

Input Data:
The standard format of the input data, as presented to the application input message editor is described in data macro AM0SG. Messages in the AMSG format are fully assembled and the pointer to the prime or only input block in storage is found in field CE1CR0 of the ECB. Overflow blocks are located in the random file pool storage area (short term) and forward chained to the prime block. It is the application's responsibility to manage the file pool storage area containing overflow AMSG blocks.

The RCB:
If the data input to the application message editor originated at a NEF terminal, then field CE1CR3 in the ECB is used to point to the storage location of the terminal's RCB if required by the application. The RCB record is in HOLD status. A detailed description is found in data macro CI0CO. Note that the RCB is divided in two sections: a system section and an application section. The latter can be defined and used by applications as a terminal assembly area to maintain continuity or transfer information across multiple messages input from a terminal. Under no circumstance should the application store information in the system area of the RCB. This could lead to unpredictable results.

Use Of Support Facilities

An application program can communicate with a display terminal using one of two basic methods. In one method, the display screen is left unformatted and is used in a free-form manner. In the second method, the display image is formatted by the application program by assigning control and data characters to a display image to be presented to the terminal operator. Printouts can be formatted in the same manner as a display image.

Of all the terminals supported in the TPF system, only the 3270 terminals can be used in both formatted and unformatted mode. In all other terminals, the images are left unformatted (such as the 2915 display).

A TPF system facility called Mapping Support Package can be used by application programs to construct and format application to application, application to terminal and terminal to application data sequences. As a formatter vehicle, this facility presents to the user program data which is devoid of device dependent code. This formatting capability is attained by user defined formats, or maps, which characterize input and output for display terminals and output for printer devices.

When used with input messages originating at field oriented terminals (for example, 3277 display station) the Mapping Support facility deletes device dependent control characters from the input data sequence and arranges the data in a symbolically addressable manner for the requesting user program. Similarly, output data sequences created by application programs are reformatted with the appropriate device control characters required to display the information on field oriented terminals (for example, 3270 displays) or to print the formatted data on hard copy devices (1980-24, 3284, 3286, 3287, 3288, 3289, 1977). More information on the services and use of the Mapping Support Package is found in the referenced books.

Output Interface From Application Programs

All application programs running under control of a TPF system with the Message Routing facility have one single interface for transmitting data. All data is transmitted by application programs through the ROUTC macro. If the Mapping Support Package is used by an application to format output data sequences, this support package is capable of assuming the responsibility for issuing the ROUTC macro in behalf of the application itself.

The ROUTC Macro:
The detailed description of the ROUTC macro is found in the TPF General Macros. When this macro is issued by an application program (or by the Mapping Support Package on its behalf), the data to be transmitted must be in AMSG format and the routing information must be contained in the RCPL pointed to by the contents of a specified system register. If the data to be transmitted is the response to an input message, the original RCPL passed to the application input message editor by the Message Router program can be used as the RCPL for the output data by simply reversing the origin and destination fields and the origin and destination type indicators. If the data to be transmitted is not the result of processing an input message, the RCPL must be constructed by the application program in the format specified in data macro RC0PL. In this case, the message type indicator in the RCPL must indicate an unsolicited message if the data is addressed to a terminal.

Sign/Log

It is important to clearly understand the difference between the Sign and Log functions in a system supported by the Message Routing facility of the TPF system. As already explained, the Log function is a system function and it is used by a terminal user to establish a data path from the terminal to and from an application. Terminal authorization requires the clearance of the terminal through verification of authorization. This clearance is performed, by the Log Processor, at the system level without the intervention of the application program. In other words, the establishment of the data path is conditioned to the terminal's authorization to input data to the application (which is different from being authorized to use the application).

The Sign function is an application function and may be required from a terminal user, connected through a log procedure, in order to use the application's functions. This may be needed for accounting purposes or for applications performing multiple functions each requiring different security codes or for a variety of other reasons. The class of applications requiring sign in/out procedures has a special interface which enables them to notify the Log Processor when a successful sign has been accomplished. This is necessary so that the data flowing from a terminal to the application between sign-in and sign-out. notifications does not need to be monitored by the Communication Source Program for a Log request. This special interface, however, applies only to applications receiving messages from non-SNA terminals and SNA terminals addressed by their 3270 pseudo LNIATAs. The interface to the Log Processor is identical for sign-in and sign-out notifications and is in the form of an application to application data transmission where:

A direct result of the log and sign procedures is that the Communication Source Program monitors all input to applications which do not require sign in/out procedures for Log requests. Consequently, no data message beginning with the characters LOG is allowed. As seen above, this restriction does not apply to applications requiring sign procedures.