Format of the IMS SPA for message switching

EGL defines the format of the IMS™ scratch pad area based on the following build descriptor options:

spaSize: Specifies the total length of the SPA, including the fields required by IMS (SPA length, SPA ID, and IMS transaction name) as well as the EGL requirement for a Segmentation Status Byte.
spaStatusBytePosition: This optional field is set either to 15 (if the status byte is to precede the data) or to the same value as spaSize (if the status byte follows the data).

Table 1. Format of IMS scratch pad area
Field	Length in bytes	Type of data	Description
SPA length	2	Binary	The length of the segment.
SPA ID	4	Binary	A unique name used to identify the SPA to IMS. This name must not be changed by the MPP.
IMS transaction name	8	Character	The IMS transaction name for the EGL program.
Segmentation Status Byte (Optional)	1	Hexadecimal	This optional byte is present if spaSize=n and spaStatusBytePosition=15 was specified and this is a deferred switch. It indicates whether data was saved in the work database.
Program data	Variable	Variable	This area contains the record passed on the transfer to transaction statement and received by the target program in its input record.
Segmentation Status Byte (Optional)	1	Hexadecimal	This optional byte is present if this is an immediate switch, and if spaSize=n and spaStatusBytePosition=n. (The status byte position will always be either 15, if the status byte is to precede the data, or equal to the size of the SPA if the status byte follows the data.) In this case the contents of the byte are ignored. This optional byte is also present if spaSize=n and spaStatusBytePosition=n was specified and this is a deferred switch. In this case, the byte indicates whether data was saved in the work database.

The following example shows the COBOL definition for a scratch pad area passed in either a deferred or an immediate program-to-program message switch for conversational processing. Keep in mind that PL/I requires a 4-byte length field rather than the 2-byte length field used for COBOL. Refer to the IMS/VS documentation for your system for additional information. The specific field names are used for illustrative purposes only; the actual field names might vary in the generated code.

* SPA IO area.
 01 SPA.
   05 SPA-LENGTH                PIC S9(4) COMP.
   05 SPA-ID                    PIC S9(9) COMP.
   05 IMS-TRAN-NAME             PIC X(8).
   05 CSP-OPTIONAL-SSM-BYTE     PIC X(1).      See Note 1.
   05 CSP-APPL-WS-DATA.
     10 data-item-1             PIC ........................
     10 data-item-2             PIC ........................
         .
      .
      .
   05 CSP-OPTIONAL-SSM-BYTE     PIC X(1).      See Note 2.

The following notes apply to this example:

This optional byte is present if spaSize=n and spaStatusBytePosition=15 was specified and this is a deferred switch. It indicates whether data was saved in the work database.
This optional byte is present if spaSize=n and spaStatusBytePosition=n was specified and this is an immediate switch. In this case the contents of the byte are ignored. This optional byte is also present if spaSize=n and spaStatusBytePosition=n was specified and this is a deferred switch. In this case, it indicates whether data was saved in the work database.

The data identified as "Program data" in the table above is treated as the input record for the target program. This technique enables a non-EGL program to store data in the SPA and switch to an EGL program (or a series of EGL programs) that use or modify the SPA data. The EGL program can eventually switch back to a non-EGL program with information from the EGL program contained in the SPA. Follow the IMS restrictions regarding changes in the SPA size.

SPA size and transfer record size

The following table defines how the SPA, the record specified on the transfer to transaction or show statement, and the input record for the target program are related for conversational processing.

Table 2. Relationship of IMS SPA to transfer record
Function	Data area size vs. transfer record size	Results
transfer to transaction	The size of the program data area in the SPA exceeds the size of the EGL record named in the transfer to transaction or show statement.	The program data area in the SPA is created using the entire EGL record, and the remaining bytes of SPA are initialized to blanks.
transfer to transaction	The size of the program data area in the SPA is less than that of the EGL record named in the transfer to transaction.	Extra bytes of the EGL record are truncated.
Initialization of target program's input record	Size of the program data area in the SPA exceeds the size of EGL record named as input record for the target program.	Extra bytes of the program data area in the SPA are truncated when it is moved into the input record.
Initialization of target program's input record	Size of the program data area in the SPA is less than that of the EGL record named as input record for the target program.	The input record is initialized from the program data area in the SPA, and the remaining bytes of the input record are initialized based on the data type.