NTRY

NTRY generates a program template that defines:

• The Identification Division, based on your Output preferences
• The Environment Division, based on your Output preferences
• The Data Division, including the following Working-Storage and Linkage Section structures:
  • Your database record or file definitions, based on your imported subschema
  • Your window and screen field data structures, based on your Screen Painter specifications
  • CICS EIBRCODEand DFHCOMMAREA structures
  • Your IMS PCB mask, including I/O and database PCBs, based on your data view
  • A data structure for passing data among programs, known as a Commarea; the Commarea appears in either Working-Storage or the Linkage Section, depending on your DC or UI target
  • PF key definitions, based on your specified DC or UI target
  • Flags required by AMB
• Portions of the Procedure Division, including:
  • A housekeeping routine to initialize Working-Storage fields, flags, and counters
  • Program invocation logic to initialize your program when it is invoked by a transaction ID, a window, or another program, based on your specified DC or UI target
  • Logic to send the program screen to the end user monitor

CICS

In CICS programs, NTRY also generates code to:

• Obtain addressability to Linkage Section areas passed from other programs via addresses in the program Commarea.
• Receive correct map if transaction is screen-invoked.

Syntax:

NTRY|ENTR screenname(mapsetname)]
... [errorpara]
... [RETRY|NORETRY]

Parameters:

screenname	Screen name; value must be literal (maximum 8 characters).
mapsetname	Mapset containing the screen(s) the program receives; must be a literal (maximum 7 characters). See also Remarks for CICS below.
errorpara	User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.
RETRY	Default. Accept only valid data in screen fields with assigned edits; otherwise, return screen to the terminal user for correction.
NORETRY	Accept invalid data in screen fields with assigned edits.

Comments:

• Normally, if received data fails to pass editing, AMB returns the screen, highlighting errors and displaying error messages in the SYSMSG field. Application logic executes after the received data passes editing.

  It is possible, however, to accept screens with data that does not pass editing. When NORETRY is coded, the application logic executes regardless. A set of runtime flags allow application logic to determine the success or failure of editing

  APS-EDITS-PASSED	88-level flag set to true when data for all edited fields is valid. Code IF APS-EDITS-PASSED to test whether the edit is OK.
  screenname-fieldname-FLAG	Indicator flag set to spaces when data for a specified field valid. Code IF screenname-fieldname-FLAG = SPACES to test whether the data is valid.
  screenname-fieldname-INPT	AMB-generated data field; contains data exactly as entered if the field failed to pass editing.
  APS-MSG-IO-ERROR	Applies to IMS DC only. 88-level flag set to true when a program sends a user-defined I/O error message. Code IF APS-MSG-IO-ERROR to test if message sent.
  APS-MSG-EDIT-ERROR	88-level flag set to true when a program sends a user-defined edit error message. Code IF APS-MSG-EDIT-ERROR to test whether if message sent.

• When mapsetname is not specified, AMB looks for it in the Screen Generation Parameters window information; otherwise, AMB generates a default mapset name, based upon the length of the screen name.

  Screen Name Length	Generated Mapset Name
  4 characters	screennameSET
  5 characters	screenname$
  6 characters	screenname$
  7 characters	Last character of screenname changes to $
  8 characters	Truncates eighth character of screenname; seventh character changes to $

• You can write rules, using the following names, to customize NTRY processing.

  User Rule Name	Where Included
  TP-ENTRY-EXIT-1	Bottom of APS-HOUSEKEEPING-PARA
  TP-ENTRY-EXIT-2	After APS-HOUSEKEEPING-PARA

• For more information, see Comments in the Help topic Program-Painter Keywords - All Applications.

Examples:

Generate code to receive screen CUSTORDR in mapset CUSTOR$ for a screen-invoked program. Perform MAP-ERROR-PARA when an exceptional condition occurs on the RECEIVE MAP.

 NTRY   CUSTODR(CUSTOR$) MAP-ERROR-PARA

See also Examples in Program-Painter Keywords - All Applications.

DLG

In DLG programs, NTRY also generates code to display screens.

Syntax:

NTRY|ENTR screenname
... [errorpara]
... [RETRY|NORETRY]
... [CANCEL|RETURN]
... [dataareas]

Parameters:

screenname	Screen name; value must be literal (maximum 8 characters).
errorpara	User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.
RETRY	Default. Accept only valid data in screen fields with assigned edits; otherwise, return screen to the terminal user for correction.
NORETRY	Accept invalid data in screen fields with assigned edits.
CANCEL	Default. Generate CONTROL ERRORS CANCEL (return control to ISPF when dialog error of return code 12 or higher).
RETURN	Generate CONTROL ERRORS RETURN to return control to program when dialog error occurs. See also Remarks below.
dataareas	Generate the PROCEDURE DIVISION USING statement. List user-defined data areas only, not records defined by TP-COMMAREA, TP-LINKAGE, and SCRNLIST, which automatically generate other data areas. AMB generates data areas in the following order. Data areas listed with NTRY. TP-COMMAREA record (see TP-COMMAREA). TP-LINKAGE records (see TP-LINKAGE). SCRNLIST screen records (see SCRNLIST).

Comments:

• Normally if received data fails to pass editing, AMB returns the screen, highlighting errors and displaying error messages in the SYSMSG field. Application logic executes after the received data passes editing.

  It is possible, however, to accept screens with data that does not pass editing. When NORETRY is coded, the application logic executes regardless. A set of runtime flags allow application logic to determine the success or failure of editing.

  APS-EDITS-PASSED	88-level flag set to true when data for all edited fields is valid. Code IF APS-EDITS-PASSED to test whether the edit is OK.
  screenname-fieldname-FLAG	Indicator flag set to spaces when data for a specified field valid. Code IF screenname-fieldname-FLAG = SPACES to test whether the data is valid.
  screenname-fieldname-INPT	AMB-generated data field; contains data exactly as entered if the field failed to pass editing.
  APS-MSG-EDIT-ERROR	88-level flag set to true when a program sends a user-defined edit error message. Code IF APS-MSG-EDIT-ERROR to test whether if message sent.

• Code logic in errorpara to process all ISPEXEC display service return codes with a value of 12 or higher.
• Provide errorpara to handle dialog errors when coding RETURN.
• For more information, see Comments in the Help topic Program Painter Keywords - All Applications.

Examples:

Generate code to display screen SCRA. Perform PROCESS-ISPF-ERRORS when return codes from services are greater than 12. Generate CONTROL ERRORS RETURN code so the program can control all error processing.

 NTRY   SCRA  PROCESS-ISPF-ERRORS  RETURN

See also the Examples in Program Painter Keywords - All Applications.