gtpa2m0r | Application Programming |
In the simplest configuration and application environment, each message has a uniquely identifiable terminal origin and is processed to completion without dependence on prior or subsequent messages. However, you probably do not experience this simplicity in practice. For example, you may need to build a transaction in conversational mode between a terminal operator, such as a bank teller, and application program that, perhaps, creates a new customer account. It would not be practical for the teller to enter all the data in 1 message. Rather, it should be entered in segments, consisting, for example, of name, address, telephone, initial deposit amount, other account data. This conversation requires a terminal operator-oriented record in which the status of the transaction can be stored after each message element and retrieved when the next element is entered. TPF provides the mechanism for this requirement with the following records:
The routing control block and agent assembly area predate SNA systems, although applications that use them may be accessed by SNA terminals. The scratchpad area is used only with SNA terminals.
There is one routing control block (RCB) record permanently assigned for every terminal addressed by a symbolic line, interchange, and terminal number (LN,IA,TA). The CPU ID further identifies the location of the terminal in the network. An RCB also is assigned to each symbolic line number used in a binary synchronous communication link.
When a message is received at the host from the terminal, TPF retrieves the RCB and passes it to the application message editor on data level 3. Because TPF assumes that the record may need to be modified, it is passed in hold status. While the RCB is in hold status, any further messages from the terminal associated with that RCB are queued. It is the application's responsibility to unhold the RCB when it does not need to modify the RCB or lock out other messages from the terminal.
The RCB contains a system area, which should never be modified by the application, and about 700 bytes exclusively for application use. The application area is undefined and may be used by the application in any way. It could be used, for example, for building transactions in conversational mode, as outlined above.
Airline reservation systems often use an agent assembly area (AAA) instead of an RCB. The AAA is similar in concept to and uses the same addressing mechanism as the RCB. However, it was designed expressly for airline applications and does not have a reserved system area, nor is it initially passed in hold status. Any terminal capable of accessing an AAA-dependent application is actually assigned an AAA when it logs into any application.
To provide support similar to the RCB for SNA systems, a system record and an application record are assigned to each logical unit. The system record is the node control block (NCB) and the application has no need to refer to it.
The scratchpad area (SPA) is allocated exclusively for application use, if desired. The SPA is undefined except for a 13-byte header. Your application should create a DSECT or define a structure that describes a record that suits your needs. The scratchpad area is allocated to fixed file storage and you can define it as 381 or 1055 bytes. The SPA (and NCB) records are ordered by resource identification (RID), which is in effect the network address of the logical unit.
Sometimes only a single terminal is associated with a logical unit, but in other cases, multiple terminals are associated with 1 logical unit (LU). In either case, however, the SPA records are allocated one per LU. This may not provide adequate flexibility or working storage. The application must design the record layout and a mechanism for additional file space per terminal that will meet its requirements. This will vary with the maximum number of terminals per LU, and the complexity of the application function. Possibilities include:
Since use of the SPA is optional, it is not automatically retrieved by TPF. However, a program is provided to retrieve it at your request. (See TPF ACF/SNA Data Communications Reference.) You pass control to the GETSPA program by calling the CSNB external function. For TARGET(TPF) C language programs a #pragma linkage statement must be coded before calling CSNB to allow the correct linkage to be made. In C language, the TPF_regs structure must be set up to load R1 with the address of a 5-byte parameter list, which is located on a halfword boundary. In assembler, before the ENTRC macro is invoked, R1 must be loaded with the address of a 5-byte parameter list located on a half word boundary.
You must define a structure or DSECT as follows to contain the required parameter list:
On return to the application program, conditions will be specified in register R0 as follows:
The SPA is filed using standard TPF file functions.
TPF does not recognize the origin or destination of a message beyond the logical unit. It is the responsibility of the application to design a protocol between the application program in the cluster controller and the application program in the host that will identify (in the message text) multiple terminals associated with a logical unit.
One method of handling this is with the function management (FM) header, which may be included in the text of an input or output message. The FM header provides information about the text of the message. It may be used to indicate:
The format of an FM header is:
HL CI
where:
When an FM header is provided, it must be the first part of the message text and its presence is indicated by the appropriate bit in the RCPL (in assembler RCPL2FMH=1 and in C language RCPL2FMH in rcplctl2, the RCPL control byte 2 in the c$rc0pl.h header).
The FM header may be maintained as received on input, modified or expanded, and included in the output. A unique RCPL bit indicates its inclusion in the output message (in assembler RCPL2FMO=1 and in C language RCPL2FMO in rcplctl2, the RCPL control byte 2).