Transferring control in the IMS/VS environment

Note:

Different considerations apply for transferring when IMSADF II programs are involved. For more information, see Transferring to and from IMSADF II programs.

EGL main Text UI programs that are generated for the IMS/VS target environment run as IMS™ message processing programs (MPPs).

Transferring program control with a transfer to transaction statement is not supported for IMS/VS main basic programs. A non-EGL program can invoke EGL MPP programs using an IMS™ program-to-program message switch. The following types of message switches are supported:

Immediate message switch: Program A passes control directly to a transaction that is associated with program B without first responding to the originating terminal. For a conversational MPP, the program does this by inserting the scratch pad area (SPA) using an alternate PCB that has its destination set to the new transaction name. For a nonconversational MPP, the program inserts a message using an alternate PCB that has its destination set to the new transaction name.
Deferred message switch: Program A responds to the terminal and informs IMS™ to start a transaction that is associated with program B on the next input from the terminal. For a conversational MPP, the message switch is achieved by modifying the SPA to specify the new transaction name before sending it back to IMS™ (using the I/O PCB). For a nonconversational MPP, the message switch is achieved by including the next transaction name on the map in such a way that it becomes the first 8 bytes of the input message.

The definition and generation options of the target non-EGL program or EGL program control the type of switch that is possible and the way the data is passed. Transferring from conversational to nonconversational or from nonconversational to conversational is not supported for EGL programs.

If the target transaction is an EGL program, the use of the property inputForm determines which type of message switch is valid:

If inputForm is not specified, an immediate message switch is required.
If inputForm is specified, either a deferred program-to-program message switch (EGL show statement) or an immediate program-to-program message switch (EGL transfer to transaction statement) can be used. If the immediate switch is used, the input form (identified in the inputForm property) is automatically displayed by the target program. However, this is less efficient than a deferred switch because the target program must be processed twice: once to display the input form and once to read the data entered by the program user.

If a non-EGL program does a deferred program-to-program message switch to an EGL program, the non-EGL program should turn on the modified data tag (MDT) attribute for all fields on the form and should set all other field properties to the values that were defined during form definition. If the program user requests help or if edit errors occur, the program displays default data in any fields that did not have the MDT attribute set and were not modified by the program user. The EGL program uses the defined properties for all other field properties.

If the target transaction is a non-EGL program that needs form input from the message queue at the start of processing, the EGL program should use a deferred program-to-program message switch (EGL show statement). Otherwise, the EGL program should use an immediate program-to-program message switch (EGL transfer to transaction statement).

The way data is passed is controlled by the following factors:

Whether the program is conversational or nonconversational.
Whether the switch is immediate or deferred.

Transferring between conversational programs

The following table shows the methods used to pass data between conversational programs (generated with spaSize > 0 build descriptor option).

Table 1. Program switching in conversational EGL programs (non-IMSADF interface)
Action	Immediate switch (optional input form)	Deferred switch (with input form)
Coding and generating	Define both programs as segmented = YES. Generate both programs as conversational (spaSize > 0).	Define both programs as segmented = YES. Generate both programs as conversational (spaSize > 0).
Performing the transfer	The transferring program cannot send a form. If it is an EGL program, it uses a transfer to transaction statement to send a record.	The transferring program must write the form to a message queue associated with the terminal after first writing the SPA. If it is an EGL program, it does this using a show with a form and an optional record.
Using an input form	The target program can optionally have an input form.	The target program must have an input form.
Passing a record	The record is transferred in the SPA.	The record, if any, is transferred in the SPA.
Specifying segmentation status byte	If spaStatusBytePosition is specified, the segmentation status byte is always placed in the last byte of the SPA. The target program always ignores the value of the segmentation status byte.	If spaStatusBytePosition=n is specified, the segmentation status byte is placed in either position 15 or the last byte of the SPA, based on the value of n. The target program uses the value of the segmentation status byte when there is an input form integrity problem caused by the program user pressing PA1 or PA2.
Note: The segmentation status byte specified by spaStatusBytePosition is used only for program-to-program transfers for conversational programs. The byte is present for transfers between conversational programs and other programs. However, a transferring non-EGL program should always set the byte to blank. A target non-EGL program should always ignore the value of the segmentation status byte.

Depending on whether you use a transfer to transaction or a show statement to accomplish the transfer, the following can be passed between two programs:

A scratch pad area (SPA) can be passed on either a transfer to transaction or a show statement.
An MFS map (EGL form) can be passed on a show statement only.

For more information and layouts, see Format of the IMS™ SPA for message switching and Format of the IMS™ MFS message input descriptor (MID).

A conversational program always uses an SPA. The SPA is passed on both immediate and deferred message switches. When you generate an EGL main Text UI program with spaSize > 0, EGL uses the SPA as follows:

When the transaction first starts for a user, EGL initializes the input record for that program from the data portion of the SPA.
When you use a transfer to transaction or a show statement to pass a record to another transaction, EGL sets the data portion of the SPA to the data in the specified record.

In addition, on a deferred switch, you can pass an MFS map to a terminal. EGL does this as follows:

When the transaction first starts for a user, EGL will check for a passed form. If such a form exists, EGL uses that data to initialize the input form for the program.
On a show statement, EGL sends the form to the terminal.

Conversational immediate program-to-program message switch

Conversational immediate program-to-program message switches are supported in the following situations:

Between two EGL programs.
From a non-EGL program to an EGL program.
From an EGL program to a non-EGL program.

Immediate switch between two EGL programs

With this technique, two segmented conversational EGL programs can change both the transaction name and the PSB name without presenting a form to the program user. Different FormGroups can be used by the two programs. The example below shows a skeleton definition of the two programs.

program ProgramA type textUIProgram 
  {segmented=yes, inputRecord="basicRecord1", 
   @DLI { psb="psb" } }

  // Declarations
  basicRecord1 TRANSFER_RECORD;  
  psb PSB1A;

  // FormGroup
  use FORMGX;

  function main()
    ...
    sysVar.transferName = 'trx1b';
    transfer to transaction sysVar.transferName passing basicRecord1;
    ...
  end // end main
end // end ProgramA 
    
program ProgramB type textUIProgram    // inputForm is optional
  {segmented=yes, inputRecord="basicRecord1", inputForm="form2",
   @DLI { psb="psb" } }

  // Declarations
  basicRecord1 TRANSFER_RECORD;  
  psb PSB1B;

  // FormGroup
  use FORMGY;

  function main()
    // generated EGL logic does the following:
    //   initializes basicRecord1
    //   if inputForm is specified:
    //     converses form2
    //     performs edits for form2 
    //     converses form2 until form2 passes all edits
    //   gives control to the first statement in the main function
    ...
  end // end main
end // end ProgramB

The EGL-generated program control logic automatically handles the SPA and the record (basicRecord1) that is passed from Program A to Program B. The data area of the SPAs for programs A and B must be at least large enough to hold the larger of the records involved.

Immediate switch from non-EGL program to EGL program

The non-EGL program must be an IMS™ conversational program. The EGL program must be defined similarly to program B in "Immediate switch between two EGL programs" above. The spaSize build descriptor option must specify the SPA size that is being used by the non-EGL program.

The non-EGL program must do the following:

Create the SPA in the format defined in Format of the IMS™ SPA for message switching. The data area in the SPA must match the definition of the input record expected by the EGL program. The EGL-generated program control logic removes the header information (length, SPA ID, transaction name), so the EGL program receives only the data.
If you specified spaSize=n and spaStatusBytePosition=p as build descriptor options, the segmentation status byte is at the end of the SPA, regardless of the value of spaStatusBytePosition. The non-EGL program should initialize the segmentation status byte to blank before inserting the SPA.
Insert the SPA into an alternate PCB. The alternate PCB must have its destination set to the transaction name for the EGL program.

Immediate switch from EGL program to non-EGL program

The non-EGL program must be an IMS™ conversational program. The EGL program must be defined similarly to program A in "Immediate switch between two EGL programs" above. The spaSize build descriptor option must specify the SPA size that is being used by the non-EGL program.

The non-EGL program must issue a get unique to the I/O PCB to read the SPA. For the required layout of the SPA, see Format of the IMS™ SPA for message switching. The SPA is created by the EGL program control logic. The data area of the SPA contains the record that the EGL program passed on the transfer to transaction statement.

If you specified spaSize=n and spaStatusBytePosition=p as build descriptor options, the segmentation status byte is at the end of the SPA, regardless of the value of spaStatusBytePosition. The non-EGL program should ignore the last byte of the SPA.

Conversational deferred program-to-program message switch

Conversational deferred program-to-program message switches are supported in the following situations:

Between two EGL programs.
From a non-EGL program to an EGL program.
From an EGL program to a non-EGL program.

Deferred switch between two EGL programs

With this technique, two segmented conversational EGL programs can change both the transaction name and the PSB name when a form is presented to the program user. You must use the same FormGroup for both programs. You do not have to transfer a record, but a form is required. The example below shows a skeleton definition of the two programs.

program ProgramA type textUIProgram 
  {segmented=yes, inputRecord="basicRecord2", 
   @DLI { psb="psb" } }

  // Declarations
  basicRecord2 TRANSFER_RECORD;  
  psb PSB2A;

  // FormGroup
  use FORMG2;

  function main()
    ...
    sysVar.transferName = 'trx2b';
    show form2 returning to sysVar.transferName passing basicRecord2;
    ...
  end // end main
end // end ProgramA 
    
program ProgramB type textUIProgram    // inputForm is required
  {segmented=yes, inputRecord="basicRecord2", inputForm="map2",
   @DLI { psb="psb" } }

  // Declarations
  basicRecord2 TRANSFER_RECORD;  
  psb PSB2B;

  // FormGroup
  use FORMG2;

  function main()
    // generated EGL logic does the following:
    //   initializes basicRecord2
    //   performs edits for map2 
    //   converses map2 until map2 passes all edits
    //   gives control to the first statement in the main function
    ...
  end // end main
end // end ProgramB

Deferred switch from non-EGL program to EGL program

The non-EGL program must be an IMS™ conversational program. The EGL program must be defined similarly to program B in "Deferred switch between two EGL programs" above. The spaSize build descriptor option must specify the SPA size that is being used by the non-EGL program.

The non-EGL program must do the following:

Create the SPA in the format defined in Format of the IMS™ SPA for message switching. The data area in the SPA must match the definition of the input record expected by the EGL program. The EGL program control logic removes the header information (length, SPA ID, transaction name), so the EGL program receives only the data.
If you specified spaSize=n and spaStatusBytePosition=p as build descriptor options, then you must initialize the segmentation status byte at the offset within the SPA specified by spaStatusBytePosition=p. Initialize the segmentation status byte to blank.
Insert the SPA into the I/O PCB.
Insert the MFS map (EGL form) into the I/O PCB using the message output descriptor that corresponds to the message input descriptor in the EGL program. The non-EGL program must set the modified data tag (MDT) attribute for all variable data fields on the MFS map (EGL form) to be passed to the EGL program on the deferred switch. All other attributes should be left at their default values. For the required layout of the map, see Format of the IMS™ MFS message input descriptor (MID). EGL generates a COBOL copybook for the MID/MOD record layout that should be used by the non-EGL program to ensure that the record formats match.

Deferred switch from EGL program to non-EGL program

The non-EGL program must be an IMS™ conversational program. The EGL program must be defined similarly to program A in "Deferred switch between two EGL programs" above. The EGL program must set the modified property to YES for all variable data fields on the form that are required as input in the non-EGL program. The spaSize build descriptor option must specify the SPA size that is being used by the non-EGL program.

The non-EGL program must do the following:

Issue a get unique to the I/O PCB to read the SPA. For the required layout of the SPA, see Format of the IMS™ SPA for message switching. The SPA is created by the EGL program control logic. The data area of the SPA contains the record that the EGL program passed on the show statement.
If you specified spaSize=n and spaStatusBytePosition=p as build descriptor options, the segmentation status byte is either at position 15 or at the last byte of the SPA. The non-EGL program should ignore the value of the segmentation status byte.
Issue a get next to the I/O PCB to retrieve the message input descriptor that corresponds to the message output descriptor used by the EGL program. For the required layout of the map, see Format of the IMS™ MFS message input descriptor (MID). EGL generates a COBOL copybook for the MID/MOD record layout that should be used by the non-EGL program to ensure that the record formats match.
Use the value of the map MID field EZEMAP-SSM-STATUS to determine whether there has been a MFS map (EGL form) integrity problem. If EZEMAP-SSM-FILLCHAR is true and this is not an initial SPA (that is, not the first transaction in the conversation), then an input map integrity problem has occurred, possibly because the program user has pressed PA1 or PA2. Take whatever action is appropriate for the program to recover the data that was lost from the input map. This might involve issuing an error message to the program user and restarting the transaction or taking other recovery actions depending on the program design.

Transferring between nonconversational programs

The following table shows the methods used to pass data between nonconversational programs. A nonconversational program is a main textUI program generated with the spaSize build descriptor option set to 0 (as is the default).

Table 2. Program switching in nonconversational EGL programs (non-IMSADF interface)
Action	Immediate switch (optional input form)	Deferred switch (with input form)
Coding and generating	Define both programs as segmented = YES. Generate both programs as nonconversational (spaSize = 0).	Define both programs as segmented = YES. Generate both programs as nonconversational (spaSize = 0).
Performing the transfer	The transferring program cannot send a form. If it is an EGL program, it uses a transfer to transaction with a record.	The transferring program must write the form to a message queue associated with the terminal. If it is an EGL program, it uses a show statement with a form and an optional record.
Using an input form	The target program can optionally have an input form.	The target program must have an input form.
Passing a record	The record is transferred in the message.	The record, if any, is transferred in the work database.

Depending on whether a transfer to transaction or a show statement used, the following can be passed on a transfer between two nonconversational programs:

An IMS™ message segment. See Format of EGL input message for IMS™ nonconversational message switch.
An MFS map (EGL form). The same MID and MOD definitions are used for conversational and nonconversational transfers. For the record layout and an example of the COBOL definition for a map message input descriptor (MID) for a deferred program-to-program message switch, see Format of the IMS™ MFS message input descriptor (MID).

Nonconversational immediate program-to-program message switch

Nonconversational immediate program-to-program message switches are supported in the following situations:

Between two EGL programs.
From a non-EGL program to an EGL program.
From an EGL program to a non-EGL program.

Immediate switch between two EGL programs

When developing EGL programs, this technique is the same as transferring with segmented conversational EGL programs, except that the spaSize build descriptor option is set to 0 (nonconversational). With this technique two nonconversational EGL programs can change both the transaction name and the PSB name without presenting a form to the program user. Different form groups can be used by the two programs.

The outlines of the two programs are identical to those in a conversational immediate switch between two EGL programs; the difference is in the value of the spaSize build descriptor option at generation time. For better performance, however, you may omit the inputForm for program B:

program ProgramA type textUIProgram 
  {segmented=yes, inputRecord="basicRecord1", 
   @DLI { psb="psb" } }

  // Declarations
  basicRecord1 TRANSFER_RECORD;  
  psb PSB1A;

  // FormGroup
  use FORMGX;

  function main()
    ...
    sysVar.transferName = 'trx1b';
    transfer to transaction sysVar.transferName passing basicRecord1;
    ...
  end // end main
end // end ProgramA 
    
program ProgramB type textUIProgram
  // omit inputForm for better performance
  {segmented=yes, inputRecord="basicRecord1", inputForm="form2",
   @DLI { psb="psb" } }

  // Declarations
  basicRecord1 TRANSFER_RECORD;  
  psb PSB1B;

  // FormGroup
  use FORMGY;

  function main()
    // generated EGL logic does the following:
    //   initializes basicRecord1
    //   if inputForm is specified:
    //     converses form2
    //     performs edits for form2 
    //     converses form2 until form2 passes all edits
    //   gives control to the first statement in the main function
    ...
  end // end main
end // end ProgramB

The EGL-generated program control logic automatically handles the IMS™ message that is used to transfer control and the record that is passed from program A to B.

Immediate switch from non-EGL program to EGL program

The non-EGL program must be an IMS™ nonconversational program. The EGL program must be defined similarly to program B in the nonconversational "Immediate switch between two EGL programs."

The non-EGL program must insert a message to an alternate PCB. The destination must be set to the transaction name for the EGL program. The non-EGL program must supply the header information (length, ZZ, and transaction name) in the message. For the required layout of the message, see Format of EGL input message for IMS™ nonconversational message switch. The EGL-generated program control logic automatically removes the header information, so the EGL program receives only the data.

Immediate switch from EGL program to non-EGL program

The non-EGL program must be an IMS™ nonconversational program. The EGL program must be defined similarly to program A in the nonconversational "Immediate switch between two EGL programs."

The non-EGL program must issue a get unique to the I/O PCB to retrieve the record that the EGL program passed on the transfer to transaction statement. For the required layout of the message, see Format of EGL input message for IMS™ nonconversational message switch. The EGL-generated program control logic automatically supplies the header information (length, ZZ, transaction name), so the EGL program defines only the data. However, the non-EGL program must be prepared to accept the header information.

Nonconversational deferred program-to-program message switch

Nonconversational deferred program-to-program message switches are supported in the following situations:

Between two EGL programs.
From a non-EGL program to an EGL program.
From an EGL program to a non-EGL program.

Deferred switch between two EGL programs

From an EGL developer's viewpoint, this technique is identical to transferring with segmented conversational EGL programs, except that the spaSize build descriptor option is set to 0, indicating nonconversational programs. With this technique two nonconversational EGL programs can change both the transaction name and the PSB name when a form is presented to the program user. You must use the same formGroup for both programs. You do not have to transfer a record, but a form is required.

The outlines of the two programs are identical to those in the conversational deferred switch between two EGL programs; the difference is in the value of the spaSize build descriptor option at generation time:

program ProgramA type textUIProgram 
  {segmented=yes, inputRecord="basicRecord2", 
   @DLI { psb="psb" } }

  // Declarations
  basicRecord2 TRANSFER_RECORD;  
  psb PSB2A;

  // FormGroup
  use FORMG2;

  function main()
    ...
    sysVar.transferName = 'trx2b';
    show form2 returning to sysVar.transferName passing basicRecord2;
    ...
  end // end main
end // end ProgramA 
    
program ProgramB type textUIProgram    // inputForm is required
  {segmented=yes, inputRecord="basicRecord2", inputForm="map2",
   @DLI { psb="psb" } }

  // Declarations
  basicRecord2 TRANSFER_RECORD;  
  psb PSB2B;

  // FormGroup
  use FORMG2;

  function main()
    // generated EGL logic does the following:
    //   initializes basicRecord2
    //   performs edits for map2 
    //   converses map2 until map2 passes all edits
    //   gives control to the first statement in the main function
    ...
  end // end main
end // end ProgramB

Deferred switch from non-EGL program to EGL program

The non-EGL program must be an IMS™ nonconversational program. The EGL program must be defined similarly to program B in the nonconversational "Deferred switch between two EGL programs."

The non-EGL program must do the following:

If a record is being transferred, call ELATSPUT to save the record in the work database for the EGL program. For details on using ELATSPUT, see Using the EGL COBOL runtime work database for IMS/VS.
Insert the MFS map (EGL form) to the I/O PCB using the message output descriptor that corresponds to the message input descriptor used by the EGL program. The non-EGL program must set the modified data tag (MDT) attribute for all variable data fields on the map to be passed to the EGL program on the deferred switch. All other attributes should be left at their default values. For the required layout of the map, see Format of the IMS™ MFS message input descriptor (MID). EGL generates a COBOL copybook for the MID/MOD record layout that should be used by the non-EGL program to ensure that the record formats match.

Deferred switch from EGL program to non-EGL program

The non-EGL program must be an IMS™ nonconversational program. The EGL program must be defined similarly to program A in the nonconversational "Deferred switch between two EGL programs." The EGL program must set the modified property to YES for all variable data fields on the form that are needed as input in the non-EGL program.

The non-EGL program must do the following:

Issue a get unique to the I/O PCB to retrieve the message input descriptor that corresponds to the message output descriptor used by the EGL program. For the required layout of the map, see Format of the IMS™ MFS message input descriptor (MID). EGL generates a COBOL copybook for the MID/MOD record layout that should be used by the non-EGL program to ensure that the record formats match.
If you are transferring a record, call ELATSGET to retrieve the record that the EGL program passed on the show statement from the work database. For details, see Using the EGL COBOL runtime work database for IMS/VS."

Interfacing through serial files in IMS™

EGL programs can communicate with non-EGL programs by performing add or get next statements on records in serial files that are associated with the IMS™ message queue.

The following types of programs can add records to serial files:

Main textUI programs
Main basic programs
Called programs

Only main basic programs can retrieve records from serial files (using get next).

Between EGL programs

An EGL program can add a series of serial records to the IMS™ message queue by specifying the following information in a ResourceAssociations part at generation:

Indication that the file is a message queue (fileType set to smsgq or mmsgq).
The PCB name to be used. This must be the name of an alternate PCB.

The EGL program automatically handles the IMS™ header information (segment length, ZZ, and transaction name). The transaction name is created from the default systemName specified in the ResourceAssociations part at generation time, or in the value of the resourceAssociation variable for the record (if it is used to override the default). Do not include IMS™ header information in the EGL serial record definition.

An EGL basic program, running as either an MPP or a transaction-driven batch message processing program (BMP), can then use the file to read the messages with get next statements. The EGL program automatically strips the header information from the message and puts the data into the serial record.

From non-EGL program to EGL program

A non-EGL program can write a series of records to the IMS™ message queue for later processing by an EGL basic program, running as either an MPP or a transaction-driven BMP. The non-EGL program must insert a record in the format shown in the following table to an alternate I/O PCB associated with the transaction that processes the record.

Table 3. Format of the record inserted to the message queue
Field	Length in bytes	Type of data	Description
Segment length	2	Binary	The length of the segment.
Reserved (ZZ)	2	Binary	Reserved.
IMS™ transaction name	8	Character	The IMS™ transaction name for the EGL program.
Program-defined fields	Variable	Variable	This area contains the data items defined in the EGL serial record.

An EGL basic program uses get next to read a serial file associated with the I/O PCB and then processes the message. The EGL program automatically removes the IMS™ message header (segment length, ZZ, and transaction name), so the program receives only the message data in the serial record.

From EGL program to non-EGL program

When an EGL program does an add to a serial file associated with a message queue, the EGL program automatically adds the IMS™ message header in front of the record data, and then inserts the message to the alternate PCB. The EGL program is only concerned with the actual data in the message.

A non-EGL program running as either an MPP or a transaction-driven BMP can process the message queue. The format of the message actually inserted to the message queue and received by the non-EGL program is shown in the table in the previous section, "From non-EGL program to EGL program."