SEND

Display screen data for end user response.

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

CICS
DLG
IMS DC

CICS

SEND generates a CICS SEND MAP command to send screen data to a terminal for user response, as well as a CICS RETURN command to return control to CICS.

Syntax:

[TP-]SEND screen[(mapsetname)] errorpara|*
... [TRANSID(name)]
... [NORETURN] [NOERASE]
... [CICSoption [CICSoption] ...]

Parameters:

`mapsetname`	Mapset containing the screen(s) the program receives; must be a literal (maximum 7 characters). When not specified, generates a default mapset name as per NTRY.
`errorpara\|*`	User-defined error routine to perform when an abnormal condition occurs. `Errorpara` is positional; if omitted, code an asterisk (*) in its place.
TRANSID (`name`)	Transaction code identifying the program where control returns; can be a literal (maximum 4 characters) or COBOL data name (minimum 5 characters).
NORETURN	Suppress the default generation of CICS RETURN (after a generated CICS SEND MAP call).
NOERASE	Suppress the default generation of ERASE.

Examples:

Send screen map SCRA.

Program Painter source:

SEND SCRA

Generated source:

EXEC CICS SEND MAP( 'SCRA')
    FROM(AA00-RECORD)
    MAPSET( 'SCRASET')
    CURSOR
    ERASE
    FREEKB END-EXEC.
EXEC CICS RETURN
    TRANSID( 'SCRA')
    COMMAREA(TP-COMMAREA)
    LENGTH(169) END-EXEC.
GO TO APS-USER-MAIN-PARA--EXIT.

Generate a CICS SEND MAP for map SCRA in mapset SCRASET; return to CICS with transaction code WXYZ. Override the default TRANSID specified in the Screen Painter.

Program Painter source:

SEND SCRA(SCRASET) * TRANSID('WXYZ')

Generated source:

EXEC CICS SEND MAP( 'SCRA')
    FROM(AA00-RECORD)
    MAPSET( 'SCRASET')
    CURSOR
    ERASE
    FREEKB END-EXEC.
EXEC CICS RETURN
    TRANSID( 'WXYZ')
    COMMAREA(TP-COMMAREA)
    LENGTH(169) END-EXEC.
GO TO APS-USER-MAIN-PARA--EXIT.

Generate a CICS SEND MAP for map SCRA.

Program Painter source:

SEND SCRA * NORETURN

Generated source:

EXEC CICS SEND MAP( 'SCRA')
    FROM(AA00-RECORD)
    MAPSET( 'SCRASET')
    END-EXEC.

DLG

Display screen data for end user response.

Syntax:

[TP-]SEND screen errorpara|*
... [CONTINUE|NOCONTINUE]

General Rules:

With NOCONTINUE, enter your return code checking routine under TP-SCREEN-INVOKED logic. With CONTINUE, enter your return code checking routine under SEND.

The following AMB-provided structure checks the return code after a SEND.

APS-TP-SEND-RC           PIC 9(08).
    88  OK-ON-SEND       VALUE 0.
    88  NTF-ON-SEND      VALUE 4.
    88  END-ON-SEND      VALUE 8.
    88  AB-ON-SEND       VALUE 12 16 20

Parameters:

`errorpara\|*`	User-defined error routine to perform when an abnormal condition occurs. `Errorpara` is positional; if omitted, code an asterisk (*) in its place.
CONTINUE	Execute the next instruction after the call.
NOCONTINUE	Default. Return control to the top of the program.

Examples:

Display screen SCRA. Determine whether END or RETURN was entered on the screen.

NTRY  SCRA
      IF TP-PROGRAM-INVOKED
          PERFORM  INITIALIZE-SCREEN-FIELDS
      ELSE-IF TP-SCREEN-INVOKED
          IF  END-ON-SEND
          ... OR SCRA-FUNCTION = 'E'
              /* USER ENTERED END OR RETURN
              TERM
          ELSE-IF OK-ON-SEND
              PERFORM  PROCESS-SCREEN-DATA
          ELSE
              SCRA-SYSMSG = 'INVALID OPTION'
      SEND SCRA * NOCONTINUE

Display screen SCRA. Determine whether END or RETURN was entered on the screen. Perform return code checking immediately following the SEND.

REPEAT
    SEND SCRA * CONTINUE
UNTIL APS-TP-SEND-RC > 0
    PERFORM  PROCESS-SCREEN-DATA
TERM

IMS DC

Send screen messages, in screen or record layout form, to terminals or printers.

Syntax:

 [TP-]SEND screenname|recordname errorpara|*
 ... [lterm]
 ... [keyword[+keyword] ...]

Syntax Rules:

For recordname, move the MOD name to IM-SCREEN-RECORD-MODNAME (a AMB-generated field) prior to SEND. Multisegment screens are not supported.
When coding RECORD and recordname in conversational programs, code the following statement if recordname differs from your application trancode.
```
SYM1    % &recordname-TRANCODE = "trancode"
```

General Rules:

Use the PURG and NOPURG keywords to control how AMB sends messages. When issuing multiple inserts to the same destination before reaching a SYNC point, IMS sends the messages as one multi-segmented message. If you send the message via an Express PCB, AMB issues a PURG after the insert and sends it as one single-segmented message.
When sending screens with edited fields, the value of the field variable (the COBOL name assigned during screen painting) moves to a field defined with a display format. The edited fields must contain valid values on output or the screen returns for correction.
To allow end users to send invalid or empty screen values, specify NORETRY with the NTRY keyword and use the generated flags to test for input data validity.
SEND logically terminates a program when executed; however, the program actually runs as a loop that processes multiple input messages.
To retain control in the program after sending a screen, code the CONT keyword. You can then send more than one screen or message from a program while processing a single transaction, or send multiple pages of output to the same destination.
When coding a conversational program in Online Express, AMB checks your alternate IO PCB for the following parameters:
```
EXPRESS=YESMODIFY=YESALTRESP=YES 
```
If any parameters are missing, a message warns you that, if an error occurs after successful database updates, AMB does not send a message to the originating terminal--the program simply terminates and performs a rollback of the updates.
In a single program execution, the terminal operator can page forward and backward with MFS logical paging commands. To do this:
- Ensure that all pages are for the same screen format.
- Ensure that all generated AMB screens contain a single DPAGE.
- Specify operator logical paging on the Screen Generation Parameters window in the Screen Painter.
- Specify that the trancode comes either from a screen field or from PF keys. If PF keys provide all or part of the trancode, define the PF key values on the MFS Function Key window.

Parameters:

`screenname`	Screen name; must be literal (maximum 8 characters).
`recordname`	User-defined I/O area in Working-Storage.
`errorpara\|*`	User-defined error routine to perform when an abnormal condition occurs. `Errorpara` is positional; if omitted, code an asterisk (*) in its place.
`lterm`	Logical terminal or printer where program sends message; can be a literal (maximum 8 characters) or COBOL data name (maximum 9 characters). Default is device that sends an input message to the program.
`keyword`	Valid keywords are:
	NOALTRESP	Default. Use an IO PCB, not an alternate response IO PCB to send a response to the terminal.
	ALTRESP	Use an alternate response IO PCB to send a response to the terminal.
	NOCONT	Default. Control returns to top of the Procedure Division of the sending program.
	CONT	Control returns to the instruction following call execution, that is, the next statement after the MSG-SW.
	CONTCOND	TP-CONTCOND determines if control passes to the next instruction or returns to the top of the program.
	NOEXPRESS	Default. Do not send a message for abnormal program termination.
	EXPRESS	Send a message at program termination.
	NOENDCONV	Default. Do not blank out the TRANCODE in the SPA.
	ENDCONV	Blank out the TRANCODE in the SPA.
	SCREEN	Default. Input is a AMB-painted screen. Multisegment screens are not supported.
	RECORD	Input is `recordname`. See also Considerations below.
	NOPURG	Send all messages to the same destination as one multi-segmented message. Default with NOEXPRESS keyword.
	PURG	After inserting the message, send it as one single-segmented message. Default with EXPRESS keyword.

Examples:

Send the single screen defined as output for the program.

SEND

In a program with multiple output screens, qualify the screens to send.

SEND SCRA

Send a screen using the EXPRESS PCB.

SEND SCRA * * EXPRESS

Send a screen using an alternate PCB and return to the next instruction following the call.

SEND SCRA * * CONT+ALTRESP